Visual UI Designer

Visual UI designer is a part of UbiqMobile SDK which is purposed for easy creation of user interfaces of the developed UbiqMobile applications. It supports size-independent representation of the created UI and displays its visual appearance on the simulated screen of abstract mobile device. Application UI can be created/edited either by dragging visual controls from the toolbox onto the screen, or by direct editing of special textual xml-based representation.

Contents:

General structure of visual UI designer interface

Visual UI designer is running within Microsoft Visual Studio; its own user interface consists of several panes: Application UI screen view pane (1), Application UI textual view pane (2), Control pane (3), Toolbox (4) that is actually a standard Visual Studio toolbox containing set of templates of supported UI controls, and Properties pane (5) where properties of the selected UI control are displayed.

fig1

Application UI screen view pane represents layout of the mobile device screen with UI controls. This pane supports Drag-and-Drop technology so that UI controls can be dragged and moved within the screen as well as they can be taken from the toolbox pane. By pressing Tab or Shift+Tab keys combinations it is possible to navigate through UI controls tree of the developed application – selection focus is moved to next/previous element of the tree accordingly.

Application UI textual view pane contains xml-based text of special format describing control tree (.ubiqml representation). This representation contains information about controls tree structure with full set of specified properties of each node. All changes in UI layout and controls’ properties cause synchronous changes in .ubiqml representation. Basically it is possible to edit .ubiqml representation directly in the textual view pane but it must be done with special care because there is a risk to obtain incorrect .ubiqml layout that cannot be displayed correctly on the screen and, that is more important, cannot be used correctly in the developed application.

Control pane contains the following elements:

  • Zoom control – if simulated screen occurs to be larger than the corresponding window of Visual Studio layout, it is possible to make simulated mobile screen fully visible just by changing zoom factor.
  • Simulated screen size – you can easily change simulated screen size for checking how UI of your developed application looks on devices with different screen resolutions.
  • Rotation button – this control allows you to check how UI of your application looks both on horizontal and vertical layouts of your mobile device.

Toolbox pane contains basic set of UI controls that can be used in the developed interface. It is possible to drag them from the toolbox and then drop onto the simulated UI screen.

Properties pane displays all available properties of the selected UI control. Properties for each control are listed below in “Controls classes and their properties” section of this document. Values of properties displayed in this pane are editable – all changes are displaying in visual UI design pane immediately.

Program interface for accessing .ubiqml resources

Resource files (of .ubiqml type) that are results of Visual UI Designer work, contain persistent representation of UI controls trees. To access resource data from the developed application, resources should be loaded prior to any further work with UI control tree. The initial values of controls’ properties are taken from .ubiqml resources but can be changed dynamically at any time. The detailed description of available controls and their properties is in GraphicsAPI Reference document.

The Screen class contains the following methods for work with .ubiqml resources:

void GrabResources(Assembly currentAssembly) – loads all .ubiqml resources from the current assembly into internal collection. This method must be invoked only once during assembly initialization.

For applications developing within UbiqMobile SDK, resources initialization is a part of automatically generated code. Example:


	Screen.GrabResources(Assembly.GetExecutingAssembly());
		

VisualElement Screen.CreateElement(String resourceName) – creates UI control tree from the loaded resource. Returns reference to the root element of the tree, or null if there is no .ubiqml resource with such name in the internal collection of loaded resources. Example:


	_viewScreen = Screen.CreateElement("View");
		

The VisualElement class contains method VisualElement GetChildByName(String controlName) that returns reference to the UI control with the given name (controlName) or null if there is no elements with such name. Example:


	btBack = (SelectableArea)_viewScreen.GetChildByName("ButtonBack");
	tlNumber = (TextBlock)_viewScreen.GetChildByName("TlNumber");
		

List of properties of supported UI elements

Most of UI elements properties that are available through GraphicsAPI, can also be specified within .ubiqml resources. The initial values of the properties are taken from the resource during creation of the appropriate subtree, and further they can be modified programmatically by the application code.

All UI elements properties can be divided into three categories: properties that are common for all UI elements (such as size), common for group of UI elements (e.g., font parameters for elements containing text strings) and specific for given particular element (such as pair of images for ImageButton).

Properties can be of the following types:

  • String – string type
  • Enum – one of fixed set of values; all possible values are specified in the description
  • Boolean – Boolean type
  • Breadth – special type representing adaptive size. It is specified by positive real number and measurement unit. Values of this types are purposed for defining sizes that are fixed within each application instance but depend on screen size of the client mobile devices. In fact, values of Breadth type are sort of embedded macros that are evaluated depending on particular client device parameters. The following measurement units are supported:
    • Absolute – size is measuring in pixels (this is a default value for object of Breadth type)
    • Small – a value calculated in according to client device screen size; can be treated as font size for small text labels
    • Medium – a value calculated in according to client device screen size; can be treated as font size for the majority of text labels
    • Large – a value calculated in according to client device screen size; can be treated as font size for headers and other important text labels
    • ExtraLarge – a value calculated in according to client device screen size; can be treated as font size for top title headers
    • ScreenWidth – calculated value that is equal to client screen width in pixels
    • ScreenHeight – calculated value that is equal to client screen heigth in pixels
    • MaxDim – calculated value that is equal to the maximum from client screen dimensions
    • MinDim – calculated value that is equal to the minimum from client screen dimensions
  • Int – integer numeric type
  • Double – real numeric type
  • Color – color in (A, R, G, B) format
  • Brush – special type representing filling type for graphical areas. The following three types are supported:
    • SolidBrush – filling with solid color; the filling color is specified by the parameter of color type
    • GradientBrush – filling with gradient; this type of filling is currently not supported in the visual designer
    • ImageBrush – filling with graphical image is specified by two parameters – image itself and image layout type. Three types of image layout are supported: None – image is placing at the center of the filled area without any zooming; if necessary, edges of the image are cropped; Scale – image is scaled so that its size by one of dimensions to be equal to the size of the filled area by the same dimension. The dimension to scale is choosing so that the image is completely housed inside the filling area; Tile – image is cloning without scaling in the filling area, starting from the upper left corner.
  • Thickness – type representing indents. Consist of 4 components: Left, Top, Right, Bottom, each component is a value of Breadth type. The typical particular case is when all components have the same value.

Properties that are common for all UI controls

Property Name Type Description
Name String Name of UI control (unique within the whole control tree) For obtaining reference to UI control by this name, use VisualElemnt.GetChildByName() method – see details in Programming access to UI controls section
Margin Thickness Outer indent (margin)
Padding Thickness Inner indent
Origin Point Position in pixels, relative to the parent control element. Used only if the parent element is OverlayPanel
Width Breadth Width of UI control (see description of Breadth type) This property is using only if HorizontalSizeComputing==FixedSize.
Height Breadth Height of UI control (see description of Breadth type). This property is using only if VerticalSizeComputing==FixedSize.
HorizontalAlignment Enum Horizontal alignment of UI control element in the available area:

  • Left – left edge alignment
  • Center – center alignment,
  • Right – right edge alignment

This property is using when HorizontalSizeComputing==FixedSize || HorizontalSizeComputing==WrapContent

VerticalAlignment Enum Vertical alignment of UI control element in the available area:

  • Top – upper edge alignment
  • Center – center alignment
  • Bottom – lower edge alignment

This property is using if VerticalSizeComputing==FixedSize || VerticalSizeComputing==WrapContent

HorizontalSizeComputing Enum Calculation mode for the width of UI control:

  • FixedSize – fixed size; element width is specified by Width property
  • WrapContent – element width is defined by its inner content width
  • FillParent – element is “filling” all available width provided by the parent element
VerticalSizeComputing Enum Calculation mode for the height of UI control:

  • FixedSize – fixed size; element height is specified by Width property
  • WrapContent – element height is defined by its inner content width
  • FillParent – element is “filling” all available height provided by the parent element
Background Brush Brush for filling UI control background. See description of Brush type

Panels

Panels are compound controls that have no their own visual representation but determine layout of other controls (“children”). The common property for all panels is Children property that is a list of child controls. Within Visual UI Designer, there is no need to access this property explicitly because it is implicitly defined by the tree structure

StackPanel

This type of panel allows to place child controls one after the other, by horizontal or by vertical. StackPanel has the following set of available properties:

Property Name Type Description
Orientation Enum Specifies layout orientation of children controls:

  • Vertical
  • Horizontal

Listbox

This panel allows to place children controls one after other by vertical. If total size of child controls exceeds panel size, scrolling is used.

NB: For vertical list, height of all child elements should be either of FixedSize type or of WrapContent type (VerticalSizeComputing property).

Listbox has the following set of available properties:

Property Name Type Description
Orientation Enum Specifies list orientation:

  • Vertical
  • Horizontal (currently not supported)

OverlayPanel

This panel allows to place children controls in the same parent area, possible with intersection. It is the only panel where Origin property is used for defining absolute position of upper-left corner of child. If Origin property has zero value, placement of child elements is determined by their HorizontalAlignment and VerticalAlignment properties independently from other child elements.

Grid

This panel allows to place child elements in the table. Numbers of rows and columns are specified during grid initialization.

Grid has the following set of available properties:

Property Name Type Description
NumberOfColumns Int Number of columns in the table
NumberOfRows Int Number of rows in the table

Containers

Containers are compound controls that are purposed for “wrapping” other controls. By such wrapping the combined control can acquire additional properties and specific behavior.

SelectableArea

SelectableArea is a transparent container that makes the wrapped control “selectable”, i.e., selection this control on the screen will cause an event sending to the server. Such behavior is similar to the hyperlink or to the button. SelectableArea has the following set of available properties:

Property Name Type Description
Child VisualElement Child control

Cell

Cell is a transparent container purposed for wrapping other controls. This container is used for simplification of child controls’ layout. Cell has the following set of available properties:

Property Name Type Description
Child VisualElement Child control

Other Controls

Button

Button control is purposed for representing standard buttons on client device’s screen. Buttons are rendered on the phone screen in native way specific for given mobile platform. It is possible to specify on the application level only colors and text displayed on the button. Button has the following set of available properties:

Property Name Type Description
Foreground Color Text color
TextAlignment Enum Text alignment inside control:

  • Left – left edge alignment
  • Center – center alignment
  • Right – right edge alignment
FontFamily Enum Type of the used font family:

  • TimesNewRoman
  • Arial
  • Courier
FontSize Breadth Font size in Breadth units. See description of Breadth type
FontStyle Enum Font style. It is possible to use combinations of several options:

  • Regular – regular style; all other options are off
  • Bold
  • Italic
  • Underline
  • Strikeout
Text String Text displayed on the button

Checkbox

This UI control represents to-state flags. The state of this flag can be either Checked or Unchecked. The CheckBox control includes flag itself and text comment that is placed at the right from the flag.

Checkbox has the following set of available properties:

Property Name Type Description
Foreground Color Text color
TextAlignment Enum Text alignment inside control:

  • Left – left edge alignment
  • Center – center alignment
  • Right – right edge alignment
FontFamily Enum Type of the used font family:

  • TimesNewRoman
  • Arial
  • Courier
FontSize Breadth Font size in Breadth units. See description of Breadth type
FontStyle Enum Font style. It is possible to use combinations of several options:

  • Regular – regular style; all other options are off
  • Bold
  • Italic
  • Underline
  • Strikeout
Text String Text displayed on the button
Checked Boolean Value by default
Clickable Boolean Determines whether event should be sent to the server when flag state changes

Dropbox

DropBox control represents drop-down list of text strings from which one can select some (single) element.

Dropbox has the following set of available properties:

Property Name Type Description
Items String[] List of strings that are displayed in the drop-down list
InitialPosition Int Default index of the selected element
Foreground Color Text color
TextAlignment Enum Text alignment inside control:

  • Left – left edge alignment
  • Center – center alignment
  • Right – right edge alignment
FontFamily Enum Type of the used font family:

  • TimesNewRoman
  • Arial
  • Courier
FontSize Breadth Font size in Breadth units. See description of Breadth type
FontStyle Enum Font style. It is possible to use combinations of several options:

  • Regular – regular style; all other options are off
  • Bold
  • Italic
  • Underline
  • Strikeout
Clickable Boolean Determines whether it is necessary to send server event by selection of the element from the list

ImageBlock

ImageBlock control is purposed for displaying of graphical images on the screen of mobile device in the same way like TextBlock control is purposed for displaying textual strings.

ImageBlock has the following set of available properties:

Property Name Type Description
Image String Name of file (or resource) containing source image
Stretch Boolean Image scaling flag. If this property value is False, in case of decrease of the size the image is cropped according to the alignment attributes; in case of increase of the size – image is placing within parent control area without scaling

ImageButton

ImageButton control allows the developer to define custom buttons. ImageButton button is specified by pair of images corresponding to pressed and depressed states of the button.

ImageButton has the following set of available properties:

Property Name Type Description
Image String Name of image file (or resource) corresponding to depressed state of the button
SelectedImage String Name of image file (or resource) corresponding to the pressed state of the button
Stretch Boolean Image scaling flag. If this property value is False, in case of decrease of the size the image is cropped according to the alignment attributes; in case of increase of the size – image is placing within parent control area without scaling

TextField

TextField control represents text input field.

TextField has the following set of available properties:

Property Name Type Description
Foreground Color Text color
TextAlignment Enum Text alignment inside control:

  • Left – left edge alignment
  • Center – center alignment
  • Right – right edge alignment
FontFamily Enum Type of the used font family:

  • TimesNewRoman
  • Arial
  • Courier
FontSize Breadth Font size in Breadth units. See description of Breadth type
FontStyle Enum Font style. It is possible to use combinations of several options:

  • Regular – regular style; all other options are off
  • Bold
  • Italic
  • Underline
  • Strikeout
Text String Text string displayed in the field
Clickable Boolean Defines whether server event should be sent when user input in the field is finished
Prompt Boolean Initial text filling mode:

  • True – Text field contains user prompt line that disappears when the user starts input
  • False – Text field contains initial value of the entered text that can be edited during user input
InputMode Enum Input mode:

  • Text – text input
  • Numeric – numeric input only
  • SecureText – invisible input (for password)
  • SecureNumeric – invisible numeric input

TextLabel

TextLabel control represents static text block.

TextLabel has the following set of available properties:

Property Name Type Description
Foreground Color Text color
TextAlignment Enum Text alignment inside control:

  • Left – left edge alignment
  • Center – center alignment
  • Right – right edge alignment
FontFamily Enum Type of the used font family:

  • TimesNewRoman
  • Arial
  • Courier
FontSize Breadth Font size in Breadth units. See description of Breadth type
FontStyle Enum Font style. It is possible to use combinations of several options:

  • Regular – regular style; all other options are off
  • Bold
  • Italic
  • Underline
  • Strikeout
Text String The displayed text

Primitive shapes

For displaying simple shapes on the screen of mobile device, there are several types of controls.

Rectangle

Rectangle control is used for displaying rectangles. There are following properties available:

Property Name Type Description
Foreground Color Rectangle border color
StrokeThickness Double Border thickness

Ellipse

Ellipse control is used for displaying ellipses inscribed in the rectangular area. There are following properties available:

Property Name Type Description
Foreground Color Ellipse border color
StrokeThickness Double Border thickness

Line

Line control is used for displaying of straight lines segments. Line is considered as inscribed into rectangular area. There are following properties available for this control:

Property Name Type Description
Foreground Color Line border color
StrokeThickness Double Border thickness
Direction Enum Line direction within enveloping rectangle:

  • None – line is not displayed
  • Vertical – vertical direction (position is determined by common alignment properties)
  • Horizontal – horizontal direction (position is determined by common alignment properties)
  • DiagonalDown – line is directed from upper left to down right corner
  • DiagonalUp – line is directed from down left to upper right corner

Compound elements

In addition to the standard set of elementary controls, visual UI designer supports extended set of compound controls which are actually frequently used combinations of elementary controls with predefined properties values. Elements from the extended set are available from Toolbox pane in the same way like standard elementary controls. Users can create their own sets of compound elements as well.

Compound elements from the extended set

  • Button in cell
  • TextField in cell
  • TextLabel in cell

All three compound elements are used for simplification of placing small-sized controls in bigger area of the screen. The inner control (button, text field, text label) has WrapContent sizing mode (by default), while enveloping Cell has FillParent sizing mode. This allows, on the one hand, to place all available space and share common space between several elements proportionally (for example, when several buttons are placed in a horizontal stack panel) and, on the other hand, have a freedom of placing inner element (button, text field or text label) at any place of the cell, according to alignment properties.

Using Visual UI designer for creating custom compound elements

Creation of custom compound element is in general similar to the creation of screen layout – the major difference is that for compound element the user should explicitly specify size of the root element (Width and/or Height). The new element will be displayed on the simulated screen according to simulated screen size (screen size can be changed from Control pane, see General Structure of Visual UI designer Interface section). For access to the new element from the program one should use Screen.CreateElement method with a parameter – name of .ubiqml resource containing compound element layout. See details in Program interface for accessing .ubiqml resources section.

Got question? Need help? Found a bug?

Feel free to ask question, report a bug or email us.