YaST2 Developers Documentation: UI built-in functions



UI built-in functions

AskForExistingDirectory ( string startDir, string headline ) -> string

Open a directory selection box and prompt the user for an existing directory.

startDir is the initial directory that is displayed.

headline is an explanatory text for the directory selection box. Graphical UIs may omit that if no window manager is running.

Returns the selected directory name or nil if the user canceled the operation.

AskForExistingFile ( string startWith, string filter, string headline ) -> string

Open a file selection box and prompt the user for an existing file.

startWith is the initial directory or file.

filter is one or more blank-separated file patterns, e.g. "*.png *.jpg"

headline is an explanatory text for the file selection box. Graphical UIs may omit that if no window manager is running.

Returns the selected file name or nil if the user canceled the operation.

AskForSaveFileName ( string startWith, string filter, string headline ) -> string

Open a file selection box and prompt the user for a file to save data to. Automatically asks for confirmation if the user selects an existing file. A

startWith is the initial directory or file.

filter is one or more blank-separated file patterns, e.g. "*.png *.jpg"

headline is an explanatory text for the file selection box. Graphical UIs may omit that if no window manager is running.

Returns the selected file name or nil if the user canceled the operation.

BusyCursor () -> void

Sets the mouse cursor to the busy cursor, if the UI supports such a feature.

This should normally not be necessary. The UI handles mouse cursors itself: When input is possible (i.e. inside UserInput() ), there is automatically a normal cursor, otherwise, there is the busy cursor. Override this at your own risk.

ChangeWidget ( `id( any widgetId ), symbol property, any newValue ) -> boolean
ChangeWidget ( symbol widgetId, symbol property, any newValue ) -> boolean

Changes a property of a widget of the topmost dialog. id specified the widget to change, property specifies the property that should be changed, newvalue gives the new value.

For example in order to change the label of a TextEntry with id `name to "anything", you write ChangeWidget( `id(`name), `Label, "anything" ).

Returns true on success.

CheckShortcuts () -> void

Perform an explicit shortcut check after postponing shortcut checks. Use this after calling PostponeShortcutCheck().

The normal sequence looks like this:

PostponeShortcutChecks();
ReplaceWidget( ... );
ReplaceWidget( ... );
...
ReplaceWidget( ... );
CheckShortcuts();
...
UserInput();

CloseDialog () -> boolean

Closes the most recently opened dialog. It is an error to call CloseDialog if no dialog is open.

Returns true on success.

DumpWidgetTree () -> void

Debugging function: Dump the widget tree of the current dialog to the log file.

FakeUserInput ( any nextUserInput ) -> void
FakeUserInput () -> void

Prepare a fake value for the next call to UserInput() - i.e. the next UserInput() will return exactly this value. This is only useful in connection with macros.

If called without a parameter, the next call to UserInput() will return "nil".

GetDisplayInfo () -> map

Get information about the current display and the UI's capabilities.

Returns a map with the following contents:

integer
Width integer The overall display width.

Unit: characters for text mode UIs, pixels for graphical UIs.

-1 means unknown.

Height integer The overall display height.

-1 means unknown.

Depth integer The display color depth. Meaningful only for graphical displays.

-1 means unknown.

Colors The number of colors that can be displayed simultaneously at any one time.

-1 means unknown.

DefaultWidth integer The width of a `opt( `defaultsize ) dialog.
DefaultHeight integer The height of a `opt( `defaultsize ) dialog.
TextMode boolean true if text mode only supported. Don't misuse this! See remark below.
HasImageSupport boolean true if images can be displayed.
HasLocalImageSupport boolean true if images can be loaded from local files rather than having to use SCR::Read( .target.byte, ... ).
HasAnimationSupport boolean true if animations can be displayed, i.e. if the Image widget supports `opt( `animated ).
HasIconSupport boolean true if icons can be displayed.
HasFullUtf8Support boolean true if all UTF-8 characters can be displayed simultaneously.

Important: Don't misuse this function to simply not support the NCurses UI properly! Always think twice before checking for text mode. If you think there is no proper layout etc. solution for NCurses, it might be time to reconsider the complexity or even the concept of your dialog.

GetLanguage ( boolean strip_encoding ) -> string

Retrieves the current language setting from of the user interface. Since YaST2 is a client server architecture, we distinguish between the language setting of the user interface and that of the configuration modules. If the module or the translator wants to know which language the user currently uses, it can call GetLanguage. The return value is an ISO language code, such as "de" or "de_DE".

If "strip_encoding" is set to "true", all encoding or similar information is cut off, i.e. everything from the first "." or "@" on. Otherwise the current contents of the "LANG" environment variable is returned ( which very likely ends with ".UTF-8" since this is the encoding YaST2 uses internally).

GetModulename ( ) -> string

This is tricky. The UI doesn't care about the current module name, only the translator does. However, since the translator acts as a filter between a client and the UI, it cant directly return the module name. The current implementation inserts the modules name in the translator and it arrives here as the term argument. So the example has no arguments, but the internal code checks for a string argument.

Example:

GetModulename()

GetProductName () -> string

Returns the current product name ("SuSE Linux", "United Linux", etc.) for display in dialogs. This can be set with SetProductName().

Note: In help texts in RichText widgets, a predefined macro &product; can be used for the same purpose.

Example:

sformat( "Welcome to %1", GetProductName() );

Glyph ( symbol glyph ) -> string

Return a special character ( a 'glyph' ) according to the symbol specified.

Not all UIs may be capable of displaying every glyph; if a specific UI doesn't support it, a textual representation ( probably in plain ASCII ) will be returned.

This is also why there is only a limited number of predefined glyphs: An ASCII equivalent is required which is sometimes hard to find for some characters defined in Unicode / UTF-8.

Please note the value returned may consist of more than one character; for example, Glyph( `ArrowRight ) may return something like "->".

Predefined glyphs include:

  • `ArrowLeft
  • `ArrowRight
  • `ArrowUp
  • `ArrowDown
  • `CheckMark
  • `BulletArrowRight
  • `BulletCircle
  • `BulletSquare

If an unknown glyph symbol is specified, 'nil' is returned.

See also the Glyphs.ycp UI example:
Glyphs in the Qt UI

Glyphs in the NCurses UI

MakeScreenShot ( string filename ) -> void

Make a screen shot if the specific UI supports that. The Qt UI opens a file selection box if filename is empty.

NormalCursor () -> void

Sets the mouse cursor to the normal cursor ( after BusyCursor ), if the UI supports such a feature.

This should normally not be necessary. The UI handles mouse cursors itself: When input is possible (i.e. inside UserInput() ), there is automatically a normal cursor, otherwise, there is the busy cursor. Override this at your own risk.

OpenDialog ( term options, term widget ) -> boolean

Same as the OpenDialog with one argument, but you can specify options with a term of the form `opt.

The option `defaultsize makes the dialog be resized to the default size, for example for the Qt interface the -geometry option is honored and for ncurses the dialog fills the whole window.

The option `centered centers the dialog to the desktop. This has no effect for popup dialogs that are a child of a `defaultsize dialog that is currently visible.

The option `decorated add a window border around the dialog, which comes in handy if no window manager is running. This option may be ignored in non-graphical UIs.

`smallDecorations tells the window manager to use only minimal decorations - in particular, no title bar. This is useful for very small popups (like only a one line label and no button). Don't overuse this. This option is ignored for `defaultsize dialogs.

The option `warncolor displays the entire dialog in a bright warning color.

The option `infocolor is a less intrusive color.

Example:

OpenDialog( `opt( `defaultsize ), `Label( "Hi" ) )

OpenDialog ( term widget ) -> boolean

Opens a new dialog. widget is a term representation of the widget being displayed. See the widget documentation for details what widgets are available. All open dialogs are arranged in a stack. A newly opened dialog is put on top of the stack. All operations implicitely refer to the topmost dialog. The user can interact only with that dialog. The application does not terminate if the last dialog is closed.

Returns true on success.

Example:

OpenDialog( `Label( "Please wait..." ) )

PlayMacro ( string macroFileName ) -> void

Execute everything in macro file "macroFileName". Any errors are sent to the log file only. The macro can be terminated only from within the macro file.

PollInput () -> any

Doesn't wait but just looks if the user has clicked some button, has closed the window or has activated some widget that has the `notify option set. Returns the id of the widget that has been selected or `cancel if the user selected the implicite cancel button ( for example he closes the window). Returns nil if no user input has occured.

Read more details and usage example in the YaST2 UI Event Handling Documentation.

PostponeShortcutCheck () -> void

Postpone keyboard shortcut checking during multiple changes to a dialog.

Normally, keyboard shortcuts are checked automatically when a dialog is created or changed. This can lead to confusion, however, when multiple changes to a dialog ( repeated ReplaceWidget() calls ) cause unwanted intermediate states that may result in shortcut conflicts while the dialog is not final yet. Use this function to postpone this checking until all changes to the dialog are done and then explicitly check with CheckShortcuts(). Do this before the next call to UserInput() or PollInput() to make sure the dialog doesn't change "on the fly" while the user tries to use one of those shortcuts.

The next call to UserInput() or PollInput() will automatically perform that check if it hasn't happened yet, any an error will be issued into the log file.

Use only when really necessary. The automatic should do well in most cases.

The normal sequence looks like this:

PostponeShortcutChecks();
ReplaceWidget( ... );
ReplaceWidget( ... );
...
ReplaceWidget( ... );
CheckShortcuts();
...
UserInput();

QueryWidget ( `id( any id ), symbol | term property ) -> any
QueryWidget ( symbol widgetId ), symbol | term property ) -> any

Queries a property of a widget of the topmost dialog. For example in order to query the current text of a TextEntry with id `name, you write QueryWidget( `id(`name), `Value ). In some cases the propery can be given as term in order to further specify it. An example is QueryWidget( `id( `table ), `Item( 17 ) ) for a table where you query a certain item.

RecalcLayout () -> void

Recompute the layout of the current dialog.

This is a very expensive operation.

Use this after changing widget properties that might affect their size - like the a Label widget's value. Call this once ( ! ) after changing all such widget properties.

Recode ( string from, string to, string text ) -> any

Recode encoding of string from or to "UTF-8" encoding. One of from/to must be "UTF-8", the other should be an iso encoding specifier (i.e. "ISO-8859-1" for western languages, "ISO-8859-2" for eastern languages, etc. )

RecordMacro ( string macroFileName ) -> void

Begin recording a macro. Write the macro contents to file "macroFilename".

RedrawScreen () -> void

Redraws the screen after it very likely has become garbled by some other output.

This should normally not be necessary: The ( specific ) UI redraws the screen automatically whenever required. Under rare circumstances, however, the screen might have changes due to circumstances beyond the UI's control: For text based UIs, for example, system commands that cause output to every tty might make this necessary. Call this in the YCP code after such a command.

ReplaceWidget ( `id( any id ), term newWidget ) -> boolean
ReplaceWidget ( symbol id, term newWidget ) -> boolean

Replaces a complete widget (or widget subtree) with an other widget (or widget tree). You can only replace the widget contained in a ReplacePoint. As parameters to ReplaceWidget specify the id of the ReplacePoint and the new widget.

This is an example:

OpenDialog( `ReplacePoint( `id( `rp ), `PushButton( "OK" ) ) );
...
ReplaceWidget( `id( `rp ), `Label( "Label" ) )

RunPkgSelection ( `id( any pkgSelId ) -> any

Not to be used outside the package selection Initialize and run the PackageSelector widget identified by 'pkgSelId'. Black magic to everybody outside. ;- )

Returns `cancel if the user wishes to cancel his selections.

SetConsoleFont ( string console_magic, string font, string screen_map, string unicode_map, string encoding ) -> nil

Switches the text console to the specified font. See the setfont(8) command and the console HowTo for details.

Example:

SetConsoleFont( "( K", "lat2u-16.psf", "latin2u.scrnmap", "lat2u.uni", "latin1" )

SetFocus ( `id( any widgetId ) ) -> boolean
SetFocus ( symbol widgetId ) ) -> boolean

Sets the keyboard focus to the specified widget. Notice that not all widgets can accept the keyboard focus; this is limited to interactive widgets like PushButtton, TextEntry, SelectionBox etc. - manager widgets like VBox, HBox etc. will not accept the keyboard focus. They will not propagate the keyboard focus to some child widget that accepts the focus. Instead, an error message will be emitted into the log file.

Returns true on success (i.e. the widget accepted the focus).

SetFunctionKeys ( map fkeys ) -> void

Set the ( default ) function keys for a number of buttons.

This function receives a map with button labels and the respective function key number that should be used if on other `opt( `key_F.. ) is specified.

Any keyboard shortcuts in those labels are silently ignored so this is safe to use even if the UI's internal shortcut manager rearranges shortcuts.

Each call to this function overwrites the data of any previous calls.

Example:

SetFunctionKeys( $[ "Back": 8, "Next": 10, ... ] );

SetLanguage ( string lang, [ string encoding ] ) -> nil

Tells the ui that the user has selected another language. If the ui has any language dependend output that language setting is honored. lang is an ISO language string, such as de or de_DE. It is required to specify an encoding scheme, since not all user interfaces are capable of UTF-8.

Example:

SetLanguage( "de_DE@euro" )
Example:
SetLanguage( "en_GB" )

SetModulename ( string name ) -> void

Does nothing. The SetModulename command is introduced for the translator. But the translator sends all commands to the ui. So the ui shouldn't complain about this command.

Example:

SetModulename( "inst_environment" )

SetProductName ( string prod ) -> void

Set the current product name ("SuSE Linux", "United Linux", etc.) for display in dialogs and in RichText widgets (for help text) with the RichText &product; macro.

This product name should be concise and meaningful to the user and not cluttered with detailed version information. Don't use something like "SuSE Linux 12.3-i786 Professional". Use something like "SuSE Linux" instead.

This information can be retrieved with the GetProductName() builtin.

Example:

SetProductName( "SuSE HyperWall" );

StopRecordingMacro () -> void

Stop macro recording. This is only necessary if you don't wish to record everything until the program terminates.

TimeoutUserInput ( integer timeout_millisec ) -> any

Waits for the user to click some button, close the window or activate some widget that has the `notify option set or until the specified timeout is expired. The return value is the id of the widget that has been selected or `cancel if the user selected the implicit cancel button (for example he closes the window). Upon timeout, `timeout is returned.

Read more details and usage example in the YaST2 UI Event Handling Documentation.

UserInput () -> any

Waits for the user to click some button, close the window or activate some widget that has the `notify option set. The return value is the id of the widget that has been selected or `cancel if the user selected the implicit cancel button (for example he closes the window).

Read more details and usage example in the YaST2 UI Event Handling Documentation.

WFM/SCR ( expression ) -> any

This is used for a callback mechanism. The expression will be sent to the WFM interpreter and evaluated there. USE WITH CAUTION.

WaitForEvent () -> map
WaitForEvent ( integer timeout_millisec ) -> map

Extended event handling - very much like UserInput(), but returns much more detailed information about the event that occured in a map.

Read more details and usage example in the YaST2 UI Event Handling Documentation.

WidgetExists ( `id( any widgetId ) ) -> boolean
WidgetExists ( symbol widgetId ) ) -> boolean

Check whether or not a widget with the given ID currently exists in the current dialog. Use this to avoid errors in the log file before changing the properties of widgets that might or might not be there.

WizardCommand ( term wizardCommand ) -> boolean

Issue a command to a wizard widget with ID 'wizardId'.

This builtin is not for general use. Use the Wizard.ycp module instead.

For available wizard commands see file YQWizard.cc . If the current UI does not provide a wizard widget, 'false' is returned. It is safe to call this even for UIs that don't provide a wizard widget. In this case, all calls to this builtin simply return 'false'.

Returns true on success.


YaST2 Developers Documentation: UI built-in functions