/ 
IUP-0.305
River stage zero No dependents
/ IUP::Manual::03_Attributes

NAME

IUP::Manual::03_Attributes - Attributes concept, using attributes, common + global attributes

IUP MANUAL

INTRODUCTION

This document is intended as a reference list for common attributes used by several (or all) GUI elements and global attributes which are not associated with any element.

For more information about using attributes see Attributes Concept in IUP::Manual::01_Introduction.

Common and/or frequently used attributes

You can manipulate these attributes via Get/SetAttributes methods of particualr emlement:

my $value = $element->GetAttribute('TITLE');  #get value
$element->SetAttribute('TITLE', $value);      #set value

or via accessors:

my $value = $element->TITLE;  #get value
$element->TITLE($value);      #set value

Global Attributes

You can manipulate these attributes like this:

my $value = IUP->GetAttribute('TITLE');  #get value
IUP->SetAttribute('TITLE', $value);      #set value

COMMON ATTRIBUTES

Common Attributes

ACTIVE

Activates or inhibits user interaction.

Value: "YES" (active), "NO" (inactive).

Default: "YES"

Notes:

An interface element is only active if its native parent is also active.

ACTIVE can also be set for controls that do not have user interaction because they may have a visual feedback to indicate the inactive state.

In GTK and Motif the inactive dialogs will still be able to move, resize and change their Z-order. Although their contents will be inactive, keyboard will be disabled, and they can not be closed from the close box.

Affects: All controls that have visual representation.

BGCOLOR

Element's background color.

Value: The RGB components.

Values should be between 0 and 255, separated by a blank space. For example "255 0 128", red=255 blue=0 green=128.

Default: It is the value of the DLGBGCOLOR global attribute. On some controls if not defined will inherit the background of the native parent.

Affects: All, but with restrictions. Several controls have transparent parts that are not affected by the BGCOLOR.

See also the screenshots of the sample.c results with normal background, changing the dialog BACKGROUND, the dialog "../sample_results_bgcolor.html" and the children BGCOLOR.

See Also: "IUP::Manual::03_Attributes/FGCOLOR", "iup_globals.html#DLGBGCOLOR"

CHARSIZE

(read-only, non inheritable)

Returns the average character size of the current FONT attribute. This is the factor used by the SIZE attribute to convert its units to pixels.

CLIENTOFFSET

(read-only, non inheritable)

Returns the container offset to the Client area, see the IUP::Manual::05_DialogLayout. Useful for IUP::Frame, IUP::Tabs and IUP::Dialog that have decorations. Can also be consulted in other containers, it will return "0x0". For controls that have a native representation is only available when the control is mapped.

In GTK and Motif, for the IUP::Dialog, the dy value is negative when there is a menu. This occours because in those systems the menu is placed inside the Client Area and all children must be placed bellow the menu.

In Windows, for the IUP::Frame, the value is always "0x0" because it actually does not have a Client area, so the child is manually positioned in the expected Client area.

This attribute can be used in conjunction with the POSITION attribute of a child so the coordinates of a child relative to the native parent top-left corner can be obtained.

Value: "<dx>x<dy>", where <dx> and <dy> are integer values corresponding to the horizontal and vertical offsets, respectively, in pixels.

Affects: All elements that are containers, except menus.

See Also: SIZE, RASTERSIZE, CLIENTSIZE, POSITION

CLIENTSIZE

(read-only**, non inheritable)

Returns the container Current size, in pixels, excluding the decorations, i.e. the size of the Client area, see the IUP::Manual::05_DialogLayout. Useful for IUP::Frame, IUP::Tabs and IUP::Dialog that have decorations. Can also be consulted in other containers, it will return the Current size. For controls that have a native representation is only available when the control is mapped.

Value: "<width>x<height>", where <width> and <height> are integer values corresponding to the horizontal and vertical size, respectively, in pixels.

Affects: All elements that are containers, except menus.

Notes:

**) For IUP::Dialog CLIENTSIZE is NOT read-only, and it will define RASTERSIZE by adding the decorations to the Client size. (Since iup-3.3)

See Also: SIZE, RASTERSIZE, CLIENTOFFSET

EXPAND

(non inheritable)

Allows the element to expand, fulfilling empty spaces inside its container.

It is a non inheritable attribute, but a container can inherits its parents EXPAND attribute. So although EXPAND is non inheritable, it is inheritable for containers. So if you set it at a container it will not affect its children, but a child that is a container will get the same value if not defined at the child itself.

The expansion is done equally for all expandable elements in the same container.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "YES" (both directions), "HORIZONTAL", "VERTICAL" or "NO".

Default: "NO". For containers the default is "YES"

Affects: All elements, except menus.

FGCOLOR

Element's foreground color. Usually it is the color of the associated text.

Value: The RGB components. Values should be between 0 and 255, separated by a blank space.

Default: "0 0 0"

Affects: All.

See Also: "IUP::Manual::03_Attributes/BGCOLOR"

FLOATING

(non inheritable)

If an element has FLOATING=YES then its size and position will be ignored by the layout processing in IUP::Vbox, IUP::Hbox and IUP::Zbox. But the element size and position will still be updated in the native system allowing the usage of SIZE/RASTERSIZE and POSITION to manually position and size the element.

This is useful when you do not want that an invisible element to be computed in the box size.

If the value IGNORE is used then it will behave as YES, but also it will not update the the size and position in the native system. (since 3.3)

Value: "YES", "IGNORE" (since iup-3.3) or "NO".

Default: "NO"

Affects: All elements, except menus.

See Also: IUP::Zbox, IUP::Vbox, IUP::Hbox

FONT

Character font of the text shown in the element. Although it is an inheritable attribute, it is defined only on elements that have a native representation.

Value:

Font description containing typeface, style and size.

Default: the global attribute DEFAULTFONT.

The common format definition is similar to the the Pango library Font Description, used by GTK+2. It is defined as having 3 parts: "<font family>, <font styles> <font size>".

Font family can be a list of fonts face names, but this is only accepted in GTK. So the font family can be reduced to font face.

The supported font style is a combination of: Bold, Italic, Underline and Strikeout. The Pango format include many other definitions not supported by the common format, they are supported only by the GTK driver. Unsupported values are simply ignored.

Font size is in points (1/72 inch) or in pixels (using negative values).

The old Font Names are still supported. The old Windows FONT format is still supported in the Windows driver.

Returned values will be the same value when changing the attribute, except for the old font names that will be converted to the new common format definition.

Windows Related Notes:

The DEFAULTFONT is retrieved from the System Settings (see bellow), if this failed then "Tahoma, 10" is assumed.

The native handle can be obtained using the "HFONT" attribute.

In "Control Panel", open the "Display Properties" then click on "Advanced" and select "Message Box" and change its Font to affect the default font for applications. In Vista go to "Window Color and Appearance", then "Open Classic Appearance", then Advanced.

Motif Related Notes:

The DEFAULTFONT is retrieved from the user resource file (see bellow), if failed then "Fixed, 11" is assumed.

The X-Windows Logical Font Description format (XLFD) is also supported.

The native handle can be obtained using the "XMFONTLIST" and "XFONTSTRUCT" attributes. The selected X Logical Font Description string can be obtained from the attribute "XLFD".

You can use the xfontsel program to obtain a string in the X-Windows Logical Font Description format (XLFD). Noticed that the first size entry of the X-Windows font string format (pxlsz) is in pixels and the next one (ptSz) is in deci-points (multiply the value in points by 10).

Be aware that the resource files ".Xdefaults" and "Iup" in the user home folder can affect the default font and many others visual appearance features in Motif.

GTK2+ Related Notes:

The DEFAULTFONT is retrieved from the style defined by GNOME (see bellow), if failed "Sans, 10" is assumed.

The X-Windows Logical Font Description format (XLFD) is also supported.

The native handle can be obtained using the "PANGOFONTDESC" attribute.

Style can also be a combination of: Small-Caps, [Ultra-Light|Light|Medium|Semi-Bold|Bold|Ultra-Bold|Heavy], [Ultra-Condensed|Extra-Condensed|Condensed|Semi-Condensed|Semi-Expanded|Expanded|Extra-Expanded|Ultra-Expanded]. Those values can be used only when the string is a full Pango compliant font, i.e. no underline, no strikeout and size>0.

In GNOME, go to the "Appearance Preferences" tool, then in the Fonts tab change the Applications Font to affect the default font.

Examples::

"Times, Bold 18"
"Arial,Helvetica, 24" (list of fonts for GTK)
"Courier New, Italic Underline -30" (size in pixels)

Affects: All elements, since the SIZE attribute depends on the FONT attribute, except for menus.

Notes:

When FONT is changed and SIZE is set, then RASTERSIZE is also updated.

Since font face names are not a standard between Windows, Motif and GTK, a few names are specially handled to improve application portability. If you want to use names that work for all systems we recommend using: Courier, Times and Helvetica (same as Motif). Those names always have a native system name equivalent. If you use those names IUP will automatically map to the native system equivalent. See the table bellow:

Motif            Windows           GTK               Description
---------------- ----------------- ----------------- -------------------------------
Helvetica        Arial             Sans              without serif, variable spacing 
Courier          Courier New       Monospace         with serif, fixed spacing 
Times            Times New Roman   Serif             with serif, variable spacing

Notes: Font - Auxiliary Attributes

See FONTFACE, FONTSIZE, FONTSTYLE, FOUNDRY - they will change the FONT attribute, and depends on it. They are used only to set partial FONT parameters of style and size. To do that the FONT attribute is parsed, changed and updated to the new value in the common format definition. This means that if the attribute was set in X-Windows format or in the old Windows and IUP formats, the previous value will be replaced by a new value in the common format definition. Pango additional styles will also be removed.

FONTFACE

(read-only, non inheritable) Returns the face name of the current FONT attribute.

FONTSIZE

(non inheritable) Replaces or returns the size of the current FONT attribute.

FONTSTYLE

(non inheritable) Replaces or returns the style of the current FONT attribute.

FOUNDRY

(non inheritable) [Motif Only] Allows to select a foundry for the FONT being selected. Must be set before setting the FONT attribute.

MAXSIZE

(non inheritable) Specifies the element maximum size in pixels during the layout process.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "<width>x<height>", where <width> and <height> are integer values corresponding to the horizontal and vertical size, respectively, in pixels.

You can also set only one of the parameters by removing the other one and maintaining the separator "x", but this is equivalent of setting the other value to 0. For example: "x40" (height only = "0x40") or "40x" (width only = "40x0").

Affects: All, except menus and the dialog.

The IUP::Dialog has the same attribute but within a different behavior although with a very similar objective.

Notes:

The limits are applied during the layout computation. It will limit the Natural size and the Current size.

If the element can be expanded, then its empty space will NOT be occupied by other controls although its size will be limited.

See the IUP::Manual::05_DialogLayout for mode details on sizes.

See Also: RASTERSIZE, MINSIZE

MINSIZE

(non inheritable) Specifies the element minimum size in pixels during the layout process.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "<width>x<height>", where <width> and <height> are integer values corresponding to the horizontal and vertical size, respectively, in pixels.

You can also set only one of the parameters by removing the other one and maintaining the separator "x", but this is equivalent of setting the other value to 0. For example: "x40" (height only = "0x40") or "40x" (width only = "40x0").

Affects: All, except menus and the dialog.

The IUP::Dialog has the same attribute but within a different behavior although with a very similar objective.

Notes:

The limits are applied during the layout computation. It will limit the Natural size and the Current size.

If the element can be expanded, then its empty space will NOT be occupied by other controls although its size will be limited.

See the IUP::Manual::05_DialogLayout for mode details on sizes.

See Also: RASTERSIZE, MAXSIZE

NAME

(non inheritable) Name of the control inside the dialog. Not releated to SetName.

Value: Text.

Notes:

The NAME value will be used by GetDialogChild to find a child inside a dialog.

Affects: All controls.

See Also: GetDialogChild

POSITION

(read-only, non inheritable) The position of the element relative to the origin of the Client area of the native parent. If you add the CLIENTOFFSET attribute of the native parent, you can obtain the coordinates relative to the Window area of the native parent. See the IUP::Manual::05_DialogLayout.

It is normally read-only, but if FLOATING=YES then it can be set.

Value: "<x>,<y>", where <x> and <y> are integer values corresponding to the horizontal and vertical position, respectively, in pixels.

Affects: All, except menus.

See Also: SIZE, RASTERSIZE, FLOATING, CLIENTOFFSET

RASTERSIZE

(non inheritable) Specifies the element User size, and returns the Current size, in pixels.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "<width>x<height>", where <width> and <height> are integer values corresponding to the horizontal and vertical size, respectively, in pixels.

You can also set only one of the parameters by removing the other one and maintaining the separator "x", but this is equivalent of setting the other value to 0. For example: "x40" (height only = "0x40") or "40x" (width only = "40x0").

When this attribute is consulted the Current size of the control is returned.

Affects: All, except menus.

Notes:

When this attribute is set, it resets the SIZE attribute. So changes to the FONT attribute will not affect the User size of the element.

A User size of "0x0" can be set, it can also be set using undef.

If you wish to use the User size only as an initial size, change this attribute to undef after the control is mapped, the returned size in GetAttribute will still be the Current size.

The element is NOT immediately repositioned. Call Refresh to update the dialog layout.

Map also updates the dialog layout even if it is already mapped, so calling it or calling Show, ShowXY or Popup (they all call Map) will also update the dialog layout.

See the IUP::Manual::05_DialogLayout for mode details on sizes.

See Also: SIZE, FONT

SIZE

(non inheritable)

Specifies the element User size, and returns the Current size, in units proportional to the size of a character.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "<width>x<height>", where <width> and <height> are integer values corresponding to the horizontal and vertical size, respectively, in characters fraction unit (see Notes bellow).

You can also set only one of the parameters by removing the other one and maintaining the separator "x", but this is equivalent of setting the other value to 0. For example: "x40" (height only = "0x40") or "40x" (width only = "40x0").

When this attribute is consulted the Current size of the control is returned.

Notes:

The size units observes the following heuristics:

  • Width in 1/4's of the average width of a character for the current FONT of each control.

  • Height in 1/8's of the average height of a character for the current FONT of each control.

So, a SIZE="4x8" means 1 character width and 1 character height.

Notice that this is the average character size, the space occupied by a specific string is always different than its number of character times its average character size, except when using a monospaced font like Courier. Usually for common strings this size is smaller than the actual size, so it is a good practice to leave more room than expected if you use the SIZE attribute. For smaller font sizes this difference is more noticeable than for larger font sizes.

When this attribute is changed, the RASTERSIZE attribute is automatically updated.

SIZE depends on FONT, so when FONT is changed and SIZE is set, then RASTERSIZE is also updated.

The average character size of the current FONT can be obtained from the CHARSIZE attribute.

A User size of "0x0" can be set, it can also be set using undef.

If you wish to use the User size only as an initial size, change this attribute to undef after the control is mapped, the returned size in GetAttribute will still be the Current size.

The element is NOT immediately repositioned. Call Refresh to update the dialog layout.

Map also updates the dialog layout even if it is already mapped, so calling it or calling Show, ShowXY or Popup (they all call Map) will also update the dialog layout.

See the IUP::Manual::05_DialogLayout for mode details on sizes.

Affects: All, except menus.

See Also: FONT, RASTERSIZE, Refresh

TIP

(non inheritable)

Text to be shown when the mouse lies over the element.

Value: Text.

Notes: Check also additional TIP* attributes (Windows / Motif / GTK specific). These attributes affect the TIP display.

TIPBALLON

[Windows Only]

The tip window will have the appearance of a cartoon "balloon" with rounded corners and a stem pointing to the item.

Default: "NO"

TIPBALLONTITLE

[Windows Only]

When using the ballon format, the tip can also has a title in a separate area.

TIPBALLONTITLEICON

[Windows Only]

When using the ballon format, the tip can also has a pre-defined icon in the title area. Values can be:

"0" - No icon
"1" - Info icon
"2" - Warning icon
"3" - Error Icon
TIPBGCOLOR

[Windows and Motif Only]

The tip background color.

Default: "255 255 225" (Light Yellow)

TIPDELAY

[Windows and Motif Only]

Time the tip will remain visible.

Default: "5000"

TIPFGCOLOR

[Windows and Motif Only]

The tip text color.

Default: "0 0 0" (Black)

TIPFONT

[Windows and Motif Only]

The font for the tip text. If not defined the font used for the text is the same as the FONT attribute for the element. If the value is SYSTEM then, no font is selected and the default system font for the tip will be used.

TIPICON

[GTK only]

Name of an image to be displayed in the TIP. See IUP::Image. (GTK 2.12)

TIPMARKUP

[GTK only]

Allows the tip string to contains pango markupcommands. Can be "YES" or "NO".

Default: "NO"

Must be set before setting the TIP attribute. (GTK 2.12)

TIPRECT

(non inheritable)

Specifies a rectangle inside the element where the tip will be activated.

Format: "%d %d %d %d"="x1 y1 x2 y2".

Default: all the element area (GTK 2.12)

TIPVISIBLE

Action attribute used to show or hide the tip under the mouse cursor. Use values "YES" or "NO". This will work in GTK but it will trigger the tip state, the given value will be ignored. (GTK 2.12)

Affects: All except label, menu item and submenu item.

TITLE

(non inheritable)

Element's title. It is often used to modify some static text of the element (which cannot be changed by the user).

Value: Text.

Default: ""

Notes:

The '\n' character usually is accepted for line change (except for menus).

The "&" character can be used to define a MNEMONIC, use "&&" to show the "&" character instead on defining a mnemonic.

If a mnemonic is defined then the character relative to it is underlined and a key is associated so that when pressed together with the Alt key activates the control.

In GTk, if you define a mnemonic using "&" and the string has an underscore, then make sure that the mnemonic comes before the underscore.

In GTK, if the MARKUP attribute is defined then the title string can contains pango markup commands. Works only if a mnemonic is NOT defined in the title. Not valid for menus.

Affects: All elements with an associated text.

See Also: FONT

VALUE

(non inheritable)

Affects several elements differently - that is, its behavior is element dependent. It is often used to change the control's main value, such as the text of a IUP::Text.

For the IUP::Radio and IUP::Zbox, elements, which are categorized as composition elements, this attribute represents the element "selected" among the others in the designed composition. To change this attribute in such cases, different mechanisms are necessary according to the programming environment used. When the elements taking part in a composition were created in C, this attribute's contents is a name that must be defined by the SetName function. When the elements were created in Lua, this attribute's contents is the name of a variable - more precisely, the one receiving the return from the function that created the element you wish to select. In LED it is not possible to dynamically change the value of any attribute, so the elements created in this environment must be identified and manipulated in C by means of their identifying name.

VISIBLE

Shows or hides the element.

Value:

"YES" (visible), "NO" (hidden).

Default: "YES"

Notes:

An interface element is only visible if its native parent is also visible.

Affects:

All controls that have visual representation.

WID

(read-only) (non inheritable)

Element identifier in the native interface system.

Value:

In Motif, returns the Widget handle.

In Windows, returns the HWND handle.

In GTK, return the GtkWidget* handle.

Notes:

Verification-only attribute, available after the control is mapped.

For elements that do not have a native representation, undef is returned.

Affects: All.

X (read-only, non inheritable)

Returns the absolute horizontal position in pixels relative to the upper left corner of the screen.

Value: Integer number.

Affects: All controls that have visual representation.

Y (read-only, non inheritable)

Returns the absolute vertical position in pixels relative to the upper left corner of the screen.

Value: Integer number.

Affects: All controls that have visual representation.

ZORDER

(write-only, non inheritable)

Change the ZORDER of a dialog or control. It is commonly used for dialogs, but it can be used to control the z-order of controls in a IUP::Cbox.

Value: Can be "TOP" or "BOTTOM".

Affects: All controls that have visual representation.

Frequently used Attributes

CONTROL

Windows only. Whether the dialog is embedded inside the parent window or has a window of its own.

Value: YES or NO. If the value is YES, the dialog will appear embedded inside its parent window (you must set a parent, either with PARENTDIALOG or NATIVEPARENT, or this setting will be ignored). If the value is NO, the dialog will have its own window.

Notes:

This is useful for implementing ActiveX controls, with the help of the LuaCOM library. ActiveX controls run embedded inside another window. LuaCOM will send a window creation event the the control, passing a handle to the parent window and the size of the control. You can use this to set the dialog's NATIVEPARENT and RASTERSIZE attributes. See the LuaCOM documentation for more information.

Affects: IUP::Dialog

See Also: NATIVEPARENT, PARENTDIALOG, RASTERSIZE

CURSOR

(non inheritable)

Defines the element's cursor.

Value: Name of a cursor.

It will check first for the following predefined names:

XXX-FIXME-missing-image

Default: "ARROW"

(*) To use these cursors on Windows, the iup.rc file, provided with IUP, must be linked with the application (except when using the IUP DLL).

The GTK cursors have the same appearance of the X-Windows cursors. Althought GTK cursors can have more than 2 colors depending on the X-Server.

If it is not a pre-defined name, then will check for other system cursors. In Windows the value will be used to load a cursor form the application resources. In Motif the value will be used as a X-Windows cursor number, see definitions in the X11 header "cursorfont.h". In GTK the value will be used as a cursor name, see the GDK documentation on Cursors.

If no system cursors were found then the value will be used to try to find an IUP image with the same name. Use SetName to define a name for an IUP::Image. But the image will need an extra attribute and some specific characteristics, see notes bellow.

Notes:

For an image to represent a cursor, it should has the attribute "HOTSPOT" to define the cursor hotspot (place where the mouse click is actually effective). The default value is "0:0".

Usually only color indices 0, 1 and 2 can be used in a cursor, where 0 will be transparent (must be "BGCOLOR"). The RGB colors corresponding to indices 1 and 2 are defined just as in regular images. In Windows and GTK the cursor can have more than 2 colors. Cursor sizes are usually less than or equal to 32x32.

The cursor will only change when the interface system regains control or when IUP::Flush is called.

The Windows SDK recommends that cursors and icons should be implemented as resources rather than created at run time.

When the cursor image is no longer necessary, it must be destroyed through function Destroy. Attention: the cursor cannot be in use when it is destroyed.

Affects: IUP::Dialog, IUP::Canvas

See Also: IUP::Image

DX

Size of the horizontal scrollbar's thumbnail in any unit.

Value: Any floating-point value greater than zero and smaller than the difference between XMAX and XMIN.

Default:: "0.1"

Notes:

LINEX, XMAX and XMIN are only updated in the scrollbar when DX is updated.

When the canvas is visible, a change in DX can generate a redraw in the horizontal scrollbar on the screen.

A change in these values can affect the attribute POSX.

Affects: IUP::Canvas

See Also: SCROLLBAR

DY

Size of the vertical scrollbar's thumbnail in any unit.

Value: Any floating-point value greater than zero and smaller than the difference between YMAX and YMIN.

Default:: "0.1"

Notes:

LINEY, YMAX and YMIN are only updated in the scrollbar when DY is updated.

When the canvas is visible, a change in DY can generate a redraw in the horizontal scrollbar on the screen.

A change in these values can affect the attribute POSY.

Affects: IUP::Canvas

See Also: SCROLLBAR

ICON

Dialog's icon. This icon will be used when the dialog is minimized.

Value:

Name of a IUP image.

Default: undef

Notes:

Icon sizes are usually less than or equal to 32x32.

The Windows SDK recomends that cursors and icons should be implemented as resources rather than created at run time.

On Motif, it only works with some window managers, like mwm and gnome. Icon colors can have the BGCOLOR values, but it works better if it is at index 0.

To associate a name to element use SetName or name=>'ElemName' named parameter of new() constructor.

Affects: IUP::Dialog

See Also: IUP::Image

MASK

(non inheritable)

Defines a mask that will filter interactive text input. See also related attributes MASKCASEI, MASKINT, MASKFLOAT.

Value: string

Set to undef to remove the mask.

Notes:

Since the validation process is performed key by key when the user is typing, an intermediate value cannot be typed if it does not follow the mask rules.

Pre-Defined Masks:

DEFINITION       VALUE                                       DESCRIPTION
IUP_MASK_INT     "[+/-]?/d+"                                 integer number
IUP_MASK_UINT    "/d+"                                       unsigned integer number
IUP_MASK_FLOAT   "[+/-]?(/d+/.?/d*|/./d+)"                   floating point number
IUP_MASK_UFLOAT  "(/d+/.?/d*|/./d+)"                         unsigned floating point number
IUP_MASK_EFLOAT  "[+/-]?(/d+/.?/d*|/./d+)([eE][+/-]?/d+)?"   floating point number with exponential notation

Pattern Specification:

The pattern to be searched in the text can be defined by the rules given below.

  • "Function" codes (such as /l, /D, /w) cannot be used inside a class ([...]).

  • If the character following a / does not mean a special case (such as /w or /n), it is matched with no / - that means that /x will match only x, and not /x. If you want to match /x, use //x.

  • The caret (^) character has different meanings when used inside or outside a class - inside a class it means negative, and outside a class it is an anchor to the beginning of a line.

  • The boundary function (/b) anchors the pattern to a word boundary - it does not match anything. A word boundary is a point between a /w and a /W character.

  • Capture operators (f and g) group patterns and are also used to keep matched sections of texts.

  • A word on precedence: concatenation has precedence over the alternation (j) operator - that is, faj fej fi will match fa OR fe OR fi.

  • The @ character is used to determine that, instead of searching the text until the first match is made, the function should try to match the pattern only with the first character. If present, it must be the first character of the pattern.

  • The % character is used to determine that the text should be searched to its end, independently of the number of matches found. If present, it must be the first character of the pattern. This is only useful when combined with the capture feature.

Allowed pattern characters:

c         Matches a "c" (non-special) character
.         Matches any single character
[abc]     Matches an "a", "b" or "c" characters
[a-d]     Matches any character between "a" and "d", including them (just like[abcd])
[^a-dg]   Matches any character which is neither between "a" and "d" nor "a" "g"
/d        Matches any digit (just like [0-9])
/D        Matches any non-digit (just like [^0-9])
/l        Matches any letter (just like [a-zA-Z])
/L        Matches any non-letter (just like [^a-zA-Z])
/w        Matches any alphanumeric character (just like [0-9a-zA-Z ])
/W        Matches any non-alphanumeric character (just like [^0-9a-zA-Z ])
/s        Matches any "blank" character (TAB, SPACE, CR)
/S        Matches any non-blank character
/n        Matches a newline character
/t        Matches a tabulation character
/nnn      Matches an ASCII character with a nnn value (decimal)
/xnn      Matches an ASCII character with a nn value (hexadecimal)
/special  Matches the special character literally (/[, //, /.)
abc       Matches a sequence of a, b and c patterns in order
aj bj c   Matches a pattern a, b or c
a*        Matches 0 or more characters a
a+        Matches 1 or more characters a
a?        Matches 1 or no characters a
(pattern) Considers pattern as one character for the above
fpatterng Captures pattern for later reference
/b        Anchors to a word boundary
/B        Anchors to a non-boundary
^pattern  Anchors pattern to the beginning of a line
pattern$  Anchors pattern to the end of a line
@pattern  Returns the match found only in the beginning of the text
%pattern  Returns the firstmatch found, but searches all the text

Examples:

(my|his)            Matches both my pattern and his pattern.
/d/d:/d/d(:/d/d)?   Matches time with seconds (01:25:32) or without seconds (02:30).
[A-D]/l+            Matches names such as Australia, Bolivia, Canada or Denmark, but not England, Spain or single letters such as A.
/l/w*               my variable = 23 * width;
^Subject:[^/n]*/n   Subject: How to match a subject line.1
/b[ABab]/w*         Matches any word that begins with A or B
from:/s*/w+         Captures "sender" in a message from sender

Affects: IUP::Text,IUP::Multiline, IUP::List and IUP::Matrix

MASKCASEI

(non inheritable)

If YES, will turn the filter case insensitive.

Default: "NO"

Must be set before MASK.

Affects: IUP::Text,IUP::Multiline, IUP::List and IUP::Matrix

MASKFLOAT

(non inheritable, write only)

Defines a floating point mask with limits. Format: "%f:%f" ("min:max"). It will replace MASK.

Affects: IUP::Text,IUP::Multiline, IUP::List and IUP::Matrix

MASKINT

(non inheritable, write only)

Defines an integer mask with limits. Format: "%d:%d" ("min:max"). It will replace MASK.

Affects: IUP::Text,IUP::Multiline, IUP::List and IUP::Matrix

PARENTDIALOG

The parent dialog of a dialog.

Value: Name of a dialog to be used as parent.

Default: undef

Notes:

This dialog will be always in front of the parent dialog. If the parent is minimized, this dialog is automatically minimized. The parent dialog must be mapped before mapping the child dialog. If PARENTDIALOG is not defined then the NATIVEPARENT attribute is consulted. This one must be a native handle of an existing dialog.

To associate a name to element use SetName or name=>'ElemName' named parameter of new() constructor.

IMPORTANT: When the parent is destroyed the child dialog is also destroyed, then the CLOSE_CB callback of the child dialog is NOT called. The application must take care of destroying the children dialogs before destroying the parent. This is usually done when CLOSE_CB of the parent dialog is called.

Affects: IUP::Dialog

POSX

Thumbnail position in the horizontal scrollbar in any unit.

Value: Any floating-point value. Must be a value between XMIN and XMAX-DX.

Default: "0.0"

Notes:

When the canvas is visible, a change in POSX can generate a redraw in the horizontal scrollbar on the screen.

This attribute does not generate a redraw of the canvas. If you need a redraw call Update in SCROLL_CB.

Affects: IUP::Canvas

See Also: SCROLLBAR

POSY

Thumbnail position in the vertical scrollbar in any unit.

Value: Any floating-point value. Must be a value between YMIN and YMAX-DY.

Default: "0.0"

Notes:

When the canvas is visible, a change in POSY can generate a redraw in the vertical scrollbar on the screen.

This attribute does not generate a redraw of the canvas. If you need a redraw call Update in SCROLL_CB.

Affects: IUP::Canvas

See Also: SCROLLBAR

SCROLLBAR

(creation only)

Associates a horizontal and/or vertical scrollbar to the element.

Value: "VERTICAL", "HORIZONTAL", "YES" (both) or "NO" (none).

Default: "NO"

Notes:

The scrollbar allows you to create a virtual space associated to the element. In the image below, such space is marked in red, as well as the attributes that affect the composition of this space. In green you can see how these attributes are reflected on the scrollbar.

images/scrollbar.gif (2113 bytes)

Hence you can clearly deduce that POSX is limited to XMIN and XMAX-DX, or XMIN<=POSX<=XMAX-DX. When the virtual space has the same size as the canvas, DX equals XMAX-XMIN, the scrollbar can be automatically hidden. See the attribute XAUTOHIDE.

The same is valid for YMIN, YMAX, DY and POSY. But remember that the Y axis is oriented from top to bottom in IUP. So if you want to consider YMIN and YMAX as bottom-up oriented, then the actual YPOS must be obtained using YMAX-DY-POSY.

Important: the LINE*, *MAX and *MIN are only updated in the scrollbar when the respective D* is updated.

If you have to change the properties of the scrollbar (XMIN, XMAX and DX) but you want to keep the thumb still (if possible) in the same relative position, then you have to also recalculate its position (POSX) using the old position as reference to the new one. For example, you can convert it to a 0-1 interval and then scale to the new limits:

old_posx_relative = (old_posx - old_xmin)/(old_xmax - old_xmin)
posx = (xmax - xmin)*old_posx_relative + xmin

IUP::List and IUP::Multiline scrollbars are automatically managed and do NOT have the POS, MIN, MAX and D attributes.

Affects: IUP::List, IUP::Multiline, IUP::Canvas, POSX, XMIN, XMAX, DX, XAUTOHIDE, POSY, YMIN, YMAX, DY, YAUTOHIDE.

SHRINK

If this attribute is defined, the elements inside the dialog will try to adjust their sizes even when the dialog's size is smaller than its natural size.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Value: "YES" or "NO".

Default: "NO"

Notes:

When the user changes the size of the dialog, the elements are automatically re-distributed inside the dialog. Some elements even have their size changed if the EXPAND attribute is active. When this size is smaller than a minimum limit in which all elements still fit the dialog, the elements' distribution is no longer modified. Actually, the virtual size of the dialog remains larger than its actual size on the screen, and some elements to the right and bottom are hidden by the borders of the dialog.

The SHRINK attribute offers an alternative to this behavior. It makes the elements continue to rearrange, even if they must overlap.

The results of this new rearrangement may vary according to the elements' distribution on the dialog.

See the IUP::Manual::05_DialogLayout for more details on sizes.

Affects: IUP::Dialog

XMAX

Maximum value of the horizontal scrollbar, in any unit.

Value: Any floating-point value.

Default: "1.0"

Notes:

A change in this value will only be effective after the attribute DX is changed.

Affects: IUP::Canvas

See Also: SCROLLBAR

XMIN

Minimum value of the horizontal scrollbar, in any unit.

Value: Any floating-point value.

Default: "0.0"

Notes:

A change in this value will only be effective after the attribute DX is changed.

Affects: IUP::Canvas

See Also: SCROLLBAR

YMAX

Maximum value of the vertical scrollbar, in any unit.

Value: Any floating-point value.

Default: "1.0"

Notes:

A change in this value will only be effective after the attribute DY is changed.

Affects: IUP::Canvas

See Also: SCROLLBAR

YMIN

Minimum value of the vertical scrollbar, in any unit.

Value: Any floating-point value.

Default: "0.0"

Notes:

A change in this value will only be effective after the attribute DY is changed.

Affects: IUP::Canvas

See Also: SCROLLBAR

GLOBAL ATTRIBUTES

Global Attributes - General

(read-only)

Returns the IUP's copyright.

Ex: "Copyright (C) 1994-2004 Tecgraf/PUC-Rio and PETROBRAS S/A".

DRIVER

(read-only)

Informs the current driver being used.

Two drivers are available now, one for each platform: "GTK", "Motif" and "Win32".

LANGUAGE

The language used by some pre-defined dialogs.

Can have the values "ENGLISH" and "PORTUGUESE".

Default: "ENGLISH"

Can also be set by SetLanguage.

VERSION

(read-only)

Returns the name of IUP's version.

The value follows the "major.minor.micro" format, major referring to broader changes, minor referring to smaller changes, and micro referring to corrections only. Ex.: "1.7.2".

Global Attributes - System Control

AUTOREPEAT

[Motif Only]

Turns on/off ("YES" or "NO") the autorepeat of keyboard keys in the whole system - may be used as an optimization in high performance applications.

CONTROLKEY

(read-only)

Returns the state of the Control keys (left and right). Possible values: "ON" or "OFF".

CURSORPOS

The cursor position in absolute coordinates relative to the upper left corner of the screen. Accept values in the format "XxY" (in C "%dx%d), example "200x200". (since GTK 2.8)

KEY

(write-only)

Sends a key press and a key release messages to the element with the focus. The value is a key code. See the Keyboard Codes table for a list of the possible values.

KEYPRESS

(write-only)

Sends a key press message to the element with the focus. The value is a key code. See the Keyboard Codes table for a list of the possible values.

KEYRELEASE

(write-only)

Sends a key release message to the element with the focus. The value is a key code. See the Keyboard Codes table for a list of the possible values.

LOCKLOOP

When the last visible dialog is closed the ExitLoop function is called. To avoid that set LOCKLOOP=YES before hiding the last dialog.

Possible values: "YES" or "NO".

Default: "NO"

MODKEYSTATE

(read-only)

Returns the state of the keyboard modifier keys: Shift, Ctrl, Alt and sYs(Win/Apple). In the format of 4 characters: "SCAY". When not pressed the respective letter is replaced by a space " ".

MOUSEBUTTON (write-only)

Simulates a mouse button press or release at the given coordinates. The position is in absolute coordinates relative to the upper left corner of the screen. Accept values in the format "XxY button state" (in C "%dx%d %c %d"), example "200x200 1 1". button can be one of the IUP_BUTTON1,... definitions. state can be 1=pressed, or 0=released. The cursor position is always updated. (since GTK 2.8)

SHIFTKEY

(read-only)

Returns the state of the Shit keys (left and right). Possible values: "ON" or "OFF".

SINGLEINSTANCE

[Windows Only]

Restricts the number of instances of the application by using a name to identify it. The value must also be a partial match to the title of a dialog that will receive the COPYDATA_CB callback with the command line of the second instance. When consulted return undef if inside the second instance. So usually in the application initialization after IUP-Open|IUP/"Open">, set SINGLEINSTANCE and then consult its value, if undef abort the second instance by calling IUP-Close|IUP/"Close"> and returning from main.

UTF8AUTOCONVERT

[GTK Only]

GTK uses UTF-8 as its charset for all displayed text, so IUP will automatically convert all strings to (SetAttribute) and from (GetAttribute) UTF-8.

Default: "YES"

If the default locale is already UTF-8, but the given string is not UTF-8 then it will be assumed that the string uses the ISO8859-1 charset.

Global Attributes - System Information

COMPUTERNAME

(read-only)

Returns the hostname.

GTKDEVVERSION

(read-only) [GTK Only]

Returns the development version of the GTK toolkit. This is the version at the time the IUP library was compiled.

GTKVERSION

(read-only) [GTK Only]

Returns the run time version of the GTK toolkit. This is the version being used at the time of the IUP::Open function was called by the application.

MOTIFNUMBER

(read-only) [Motif Only]

Returns the number of the Motif Version if full form, e.x: 2.2.3 = "2203".

MOTIFVERSION

(read-only) [Motif Only]

Returns the version of the run time Motif.

SYSTEM

(read-only)

Informs the current operating system. On UNIX, it is equivalent to the command "uname -s" (sysname). On Windows, it identifies if you are on Windows 2000, Windows XP or Windows Vista. Some known names:

  • "MacOS"

  • "FreeBSD"

  • "Linux"

  • "SunOS"

  • "Solaris"

  • "IRIX"

  • "AIX"

  • "HP-UX"

  • "Win2K"

  • "WinXP"

  • "Vista"

  • "Win7"

SYSTEMLANGUAGE

(read-only)

Return respectively a text with a description of the system language.

SYSTEMVERSION

(read-only)

Informs the current operating system version number.

On UNIX, it is equivalent to the command "uname -r" (release). On Windows, it identifies the system version number and service pack version. On MacOSX is system version.

USERNAME

(read-only)

Returns the user logged in.

XSERVERVENDOR

(read-only) [GTK and Motif Only]

X-Windows Server Vendor string.

XVENDORRELEASE

(read-only) [GTK and Motif Only]

X-Windows Server Vendor release number.

Global Attributes - Screen Information

FULLSIZE

(read-only)

Returns the full screen size in pixels.

String in the "<width>x<height>" format (e.g. "800x600").

MONITORSINFO

(read-only) [Win32 and GTK Only]

Returns the position and size in pixels of all monitors. Each monitor information is terminated by a "\n" character.

String in the "<x> <y> <width> <height>\n<x> <y> <width> <height>\n..." format.

SCREENDEPTH

(read-only)

Returns the screen depth in bits per pixel.

SCREENSIZE

(read-only)

Returns the screen size in pixels available for dialogs, i.e. not including menu bars, task bars, etc. In Motif has the same value as the FULLSIZE attribute. The main screen size does not include additional monitors.

String in the "<width>x<height>" format (e.g. "300x400").

TRUECOLORCANVAS

(read-only)

Indicates if the display allows creating TrueColor (> 8bpp) IUP::Canvas controls, even if PseudoColor is the default, i.e. even if SCREENDEPTH<=8 . Returns "YES" or "NO". Usefull in Motif.

VIRTUALSCREEN

(read-only) [Win32 and GTK Only]

Returns the virtual screen position and size in pixels. It is the virtual space defined by all monitors in the system.

String in the "<x> <y> <width> <height>" format (e.g. "100 50 800 600").

Global Attributes - System Data

APPSHELL

(read-only) [Motif Only]

Returns the shell Widget created by XtOpenApplication.

DLL_HINSTANCE

[Win32 Only]

Changes and returns a handle (HINSTANCE) that identifies the DLL where resources are stored.

HINSTANCE

(read-only) [Win32 Only]

Returns a handle (HINSTANCE) that identifies the application in the native system.

XDISPLAY

(read-only) [GTK and Motif Only]

Returns the X-Windows Display.

XSCREEN

(read-only) [GTK and Motif Only]

Returns the X-Windows Screen.

Global Attributes - Default Attributes

DEFAULTFONT

The default font used by all elements, except for menus.

DEFAULTFONTSIZE

Auxiliar attribute to retrieve and set the default font size used by all elements. It retrieves the size from DEFAULTFONT. When changed will actually change the DEFAULTFONT.

DLGBGCOLOR

The default background color for all elements that have the background similar of the dialog.

DLGFGCOLOR

The default foreground color for all elements that have text over the background of the dialog or similar. Usually is "0 0 0".

The default menu background color. Usually is "255 255 255".

The default menu foreground color. Usually is "0 0 0".

TXTBGCOLOR

The default background color for editable text, also used by lists and tree. Usually is "255 255 255".

TXTFGCOLOR

The default foreground color for editable text, also used by lists and tree. Usually is "0 0 0".