Using Themes

Introduction

SXY/COM provides a default user interface consisting of a window with a SimpleGraph. Some application may desire to extend this interface, adding menus and buttons. SXY/COM allows the definition of themes, that is, customizations of the default interface. A theme may specify the menus and a single tool bar. The menus can contain items, submenus and separators. The tool bar can hold buttons and spaces. Here goes a sample of a SXY/COM customized with a theme.

Creating a Dialog with a Theme

To create a dialog with a theme, it's necessary to supply the function createSimpleGraph with an extra argument: the name of the theme. E.g.:

Set graph = sxy.createSimpleGraph(LINEAR_SIMPLE_GRAPH, 600, 400, "vcaVisual")

SXY/COM them tries to load a file called "themes\vcaVisual\vcaVisual_theme.lua", which should be in the SXY/COM installation directory (that is, the same directory of the SXY/COM executable). This file tells which changes will be made to the default interface. It's necessary to supply a name for the themes, as there may be more than one theme available.

The Customization File

The customization file specifies some itens of the interface:

	The window title.
	The hierarchy of menus.
	The buttons, their captions or icons.

Here is a sample of the contents of the theme file:

SXYTheme{
  name = "vca",
  windowTitle = "SXY/COM VCA",
  menubar = {
    { "Options", 
      {
        { "Copy graph", "copy" },
        { "Print graph", "print" },
        {},
        { "Hide graph", "hide" },
        {},
        { "Destroy graph", "destroy" }
      }
    }
  },
  toolbar = {
    { icon = "print", event = "print" },
    { icon = "copy", event = "copy" },
    {},
    { icon = "zoomin", event = "zoomin" },
    { icon = "zoomout", event = "zoomout" },
    { icon = "fit", event = "fit" }
  }
}

The top-level element of a theme is the block headed by SXYTheme. It must contain four fields:

	name,
	windowTitle,
	menubar and
	toolbar.

The field "name" is simply the name of the theme, which must match the name of the file, besides the extension "_theme.lua"; "windowTitle" is the string that should appear in the window title (notice that this can be customized directly with SXY/COM method setWindowTitle); "menubar" should contain a list of menu items in the form {menu_item1, menu_item2,..., menu_item_n}. Each menu item can be an action or a submenu. An action has the form {caption, action_name}, where caption is the name that appears in the menu and action_name is the string that will be sent to the client application when the user selects this option.

A submenu is specified slightly different: it has the form {caption, item_list}, where item_list is the list of items in the submenu, like the menubar. Here follow some samples:

A simple menu bar:


menubar = {
  {"Start", "start_action"},
  {"Exit",  "exit_action"}
}

This will create a menubar of two items, without any submenus. Normally all menus in the menu bar have submenus. Next we can build a typical "File" menu:

menubar = {
  { "File",
    {
      {"Open", "open_action"},
      {"Close", "close_action"}
    }
  }
}

This will build a menu "File" with a submenus, which has two itens. We can add a separator between two menu items:

menubar = {
  { "File",
    {
      {"Open", "open_action"},
      {},
      {"Close", "close_action"}
    }
  }
}

Submenus can be nested:

menubar = {
  { "File",
    {
      {"Open", "open_action"},
      {"New",
      	{
      	  {"Graph", "newgraph_action"},
      	  {"Curve", "newcurve_action"},
      	  { "Dataset",
            {
      	      {"From file", "datasetfromfile_action"},
      	      {"Manual entry", "datafromkeyboard_action"}
      	    }
      	  }
        }
      },
      {},
      {"Close", "close_action"}
    }
  }
}

It's recommended to indent the code to assure that all opening and closing braces match.

The toolbar field of the theme is a list of buttons, each one in the form {icon = icon_file_name, event = event_name}. where icon_file_name is the name of the file that describes the icon which SXY/COM will put inside the button. This file must have the extension .lua, e.g., "copy.lua". The event_name is the string that is sent to the client application when the user clicks on the button. An empty item, {}, inserts a space between the previous and the next button.

toolbar = {
    { icon = "print", event = "print" },
    { icon = "copy", event = "copy" },
    {},
    { icon = "zoomin", event = "zoomin" },
    { icon = "zoomout", event = "zoomout" },
    { icon = "fit", event = "fit" }
}

This toolbar description demands that five files are present in the same directory of the theme description file: print.lua, copy.lua, zoomin.lua, zoomout.lua and fit.lua. It also includes a space between the icons copy and zoomin.

Handling Events

When a menu item or a button in the toolbar is selected, SXY/COM sends an event to the client application. All events are sent through one function called genericEvent. This functions receives as arguments the SimpleGraph where the event was generated and the string describing the event. Follow a sample implementation of the event handler.

Sub sxycom_obj_evt_genericEvent(ByVal graph As Object, ByVal event_name As String)

    If event_name = "print" Then
        graph.printGraph 1
    ElseIf event_name = "copy" Then
        graph.copyGraph 600, 400
    End If

End Sub

By Vinícius Almendra