Cross-platform C SDK logo

Cross-platform C SDK

Panel

❮ Back
Next ❯
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

Panel*panel_create (void)
Panel*panel_scroll (...)
voidpanel_data (...)
type*panel_get_data (...)
voidpanel_size (...)
uint32_tpanel_layout (...)
Layout*panel_get_layout (...)
voidpanel_visible_layout (...)
voidpanel_update (...)

A Panel is a control within a window that groups other controls. It defines its own reference system, that is, if we move a panel all its descendants will move in unison since their locations will be relative to the origin of their predecessor. It will support other (sub)-panels as descendants, which allows to form a Window Hierarchy (Figure 1). For portability, this Gui library does not support specific coordinates and sizes for elements linked to a panel, but the association is carried out by a Layout object which is responsible for calculating at runtime the final locations of controls based on the platform and window manager. In Hello Subpanel! you have an elementary example of using panels.

  • Use panel_create to create a new panel.
  • Use panel_layout to add child controls to the panel.
  • Scheme showing the hierarchy produced by panels, subpanels and controls.
    Figure 1: Window hierarchy.

Each panel supports several layouts and allows you to switch between them at runtime (Figure 2). This allows to create dynamic responsive interfaces with very little effort, since the panel itself is responsible for linking and sizing the controls according to the active layout in each case. In Hello Multi-layout! you have an example.

  • Use panel_visible_layout to change the layout.
  • Two different window settings using the same controls.
    Figure 2: Panel with two different organizations for the same controls.

Because the layouts are logical structures outside the window hierarchy, they can share controls as they are linked to the same panel (Figure 3). What is not allowed is to use the same objects in different panels, due to the hierarchy concept.

Scheme showing how to correctly share the elements between layouts.
Figure 3: It is possible to reuse the same components between layouts of the same panel.

1. Scrolling panels

The final size of a panel is determined by the active Layout at this time and is sized according to the components it contains. Since no limit is set, it is possible for the panel to grow excessively large, even exceeding the size of the screen (Figure 4). Using scroll bars will solve the problem. In Hello Scroll-Panel! you have an example of use.

  • Use panel_scroll to create a panel with scroll bars.
  • Use panel_size to set the default size of the visible area.
  • Window with many controls without scroll bars. The same window with scroll bars.
    Figure 4: Panel with 100 rows of edit controls. (1) Without scroll, (2) With scroll.

In a panel with scroll bars, the dimensioning of the content and the visible area is managed separately, in such a way that we avoid the problem seen above:

  • The interior area is calculated automatically, based on the content of the layout. See Natural sizing, Margins and format.
  • The visible area is set by panel_size. The initial size may vary depending on the Cell expansion policy defined in the layout.
  • In the event that the content is less than the visible area, the corresponding scroll bar (horizontal or vertical) will disappear.

panel_create ()

Create a panel.

Panel*
panel_create(void);

Return

The new panel.


panel_scroll ()

Create a panel with scroll bars.

Panel*
panel_scroll(const bool_t hscroll,
             const bool_t vscroll);
hscroll

TRUE if we want horizontal scroll bar.

vscroll

TRUE if we want vertical scroll bar.

Return

The new panel.

Remarks

Ver Scrolling panels.


panel_data ()

Associate user data with the panel.

void
panel_data(Panel *panel,
           type **data,
           FPtr_destroy func_destroy_data,
           type);
panel

The panel.

data

User data.

func_destroy_data

Destructor of user data. It will be called when the panel is destroyed.

type

Type of user data.


panel_get_data ()

Get the user data associated with the panel.

type*
panel_get_data(const Panel *panel,
               type);
panel

The panel.

type

Type of user data.

Return

User data.


panel_size ()

Sets the default size of the visible area of ​​a panel with scroll bars.

void
panel_size(Panel *panel,
           const S2Df size);
panel

The panel.

size

The default size.

Remarks

If we pass -1 to the value of width or height, the measure of the interior area will be established. See Scrolling panels.


panel_layout ()

Add a layout to a panel.

uint32_t
panel_layout(Panel *panel,
             Layout *layout);
panel

The panel.

layout

Layout.

Return

The newly added layout index.


panel_get_layout ()

Get a layout of a panel.

Layout*
panel_get_layout(Panel *panel,
                 const uint32_t index);
panel

The panel.

index

The layout index.

Return

Layout.


panel_visible_layout ()

Set the active layout inside the panel.

void
panel_visible_layout(Panel *panel,
                     const uint32_t index);
panel

The panel.

index

The layout index.

Remarks

To make the change effective, you have to call panel_update.


panel_update ()

Update the window that contains the panel.

void
panel_update(Panel *panel);
panel

The panel.

Remarks

It is equivalent to calling window_update.

❮ Back
Next ❯