Writing stone plugins

From RockWiki

Jump to: navigation, search

Stone expects plugins (also called modules) to reside in the /etc/stone.d/ directory. This default may be changed by setting the SETUPD environment variable.

Each plugin must have a name like mod_<name>.sh. Plugins are bash scripts that can use shell functions defined by stone for basic user interface elements.

A very simple plugin looks like this: 

 # [MAIN] 99 helloworld Hello World Stone Plugin

 main() {
 	gui_message "Hello World!"
 }

The first line makes the plugin known to stone, and consists of 4 fields (beginning after the hash mark). All plugins containing a line that begins with 

 # [MAIN] xy

are listed in the main menu of stone; x and y are decimal digits, and determine the order of entries in the menu (entries with lower numbers are listed first). Other values than [MAIN] may indicate modules for sub-menus of stone.

The third field must match the file name, so this plugin would have to be called mod_helloworld.sh.

The rest of the line is the title for this module in the stone menus.

Every plugin must define a main() shell function, which is executed whenever the plugin is selected in stone. In our example the module displays a message, using the pre-defined gui_message function.

The pre-defined functions for modules in stone, as well as their usage, are:

  • 1. gui_menu "ID" "Title" "Text" "Action" [ "Text" "Action" [ .. ] ]

This command creates a submenu with the menuid ID (see submenus above), the title Title and at least one action. An action is a shell command and can either be complete shell code, a call to a function, or just an empty string to make the Text that belongs to the action a comment. Comments won't have hotkeys assigned.

  • 2. gui_input "Text" "Default" "VarName"

This command will prompt the user to input a value. The description will be Text, the default value will be Default and the variable holding the result will be VarName.

  • 3. gui_message "Text"

This command will pop up a message reading Text. This is intended for error messages. The script will block until the message is clicked away.

  • 4. gui_yesno "Text"

This command will ask the user the question Text which he can then answer with either Yes or No

  • 5. gui_edit "Text" "File"

This command will open the file File in the users preferred editor (defined by the environment variable EDITOR). Note that not all user interface plugins use Text as the window title.

  • 6. gui_cmd "Title" "Command"

This command will execute an arbitrary command and return.

Retrieved from "http://www.rocklinux.org/wiki/Writing_stone_plugins"
Personal tools