YaST2 Developers Documentation: UI built-in functions | ![]() |
![]() |
UI built-in functions
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.
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.
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.
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.
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.
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();
Closes the most recently opened dialog. It is an error to call CloseDialog if no dialog is open. Returns true on success.
Debugging function: Dump the widget tree of the current dialog to the log file.
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".
Get information about the current display and the UI's capabilities. Returns a map with the following contents:
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.
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).
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()
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() );
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:
If an unknown glyph symbol is specified, 'nil' is returned. See also the Glyphs.ycp UI example:
Glyphs in the NCurses UI
Make a screen shot if the specific UI supports that. The Qt UI opens a file selection box if filename is empty.
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.
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" ) )
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..." ) )
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.
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.
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();
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.
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 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. )
Begin recording a macro. Write the macro contents to file "macroFilename".
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.
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" ) )
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.
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" )
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).
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, ... ] );
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" )
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" )
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" );
Stop macro recording. This is only necessary if you don't wish to record everything until the program terminates.
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.
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.
This is used for a callback mechanism. The expression will be sent to the WFM interpreter and evaluated there. USE WITH CAUTION.
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.
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.
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 | ![]() |