When you click an icon in the Components palette, the corresponding embedded component is inserted in your document at the current cursor location. For example, you can insert a button  within a paragraph, or you can include a series of plot components, sliders, and check boxes that function together.

You can use a table to lay out the components in your document. To insert a table, from the Insert menu, select Table. You can then insert buttons, plots, gauges, math, text, and so on in each table cell.

Embedded components can be programmed to accomplish specific tasks when mouse actions are performed. For example, button components and sliders can be programmed to display information when they are clicked or dragged, and a plot component can be programmed to display points when it is clicked. To program an embedded component to perform a task, you must edit the properties of the embedded component and, in most cases, provide the code needed to accomplish the task.

For example, if you want to provide code for a button component, you would right-click (Control-click for Macintosh) the button component that you inserted in your document and select Properties. You would then click the Edit button beside Action When Clicked to display a window in which you can enter the code (see Figure 13.1). By default, this window contains sample code that you can start with.

Each embedded component has different properties that you can edit. For more information about the properties for a specific component, refer to the EmbeddedComponents help page and browse to the page of the component that you want to use.

Tip: If you are working with multiple components in a document, you may find it easier to include the code for all of the component actions in one area, for example, the startup code region of your document. For more information, see the worksheet,documenting,startupcode help page.

In the following example, a tic-tac-toe game will be created using embedded components in Maple. This example contains nine list boxes that are organized in a 3 by 3 table.

It is possible to associate code with each of the list boxes individually. However, if you want to change this code in the future, you would need to change it in nine places. A simpler approach is to write a Maple module that contains the code to perform the action and call that code from each list box.

Tip: Make sure that all of the embedded components in your document have unique names.

Note: You can copy and paste embedded components within a document or from one document to another. A unique name is assigned to each pasted component - the number in the component name is incremented. Other details associated with the component, for example, properties and actions, are copied in their original form.

The %this argument, which is passed as the value of the what parameter to the TicTacToe:-Select procedure, is set to the name of the component that generates the action. Therefore, the result is that if you select either the "X" or the "O" list element, the list box is dimmed and the user's selection cannot be changed.

For more information about modules, see Programming with Modules.

Alternatively, you can save this module in a Maple library archive, which is a separate file in which you can store Maple procedures, modules, and other data. For more information, refer to the repository help page.

The examples above use commands from the DocumentTools package to retrieve information from components and update component properties. This package includes the following commands.

For more information about the properties that can be retrieved and set for each component, refer to the EmbeddedComponents help page and browse to the help page of the component that you want to use.

You can specify two arguments for the DocumentTools:-GetProperty command: the name of the component and the property (or option) to be retrieved. Note: The value returned by the GetProperty command will either be a number or a string. For example, the command DocumentTools:-GetProperty( component_name, 'visible' ) returns a value of "true" or "false". To retrieve the corresponding Boolean value, the result must be processed by the parse command: parse( DocumentTools:-GetProperty( component_name, 'visible' ) ) returns a value of true or false. However, in many cases, this extra step is not necessary. For example, the comparison

will be faster than

You can specify the following arguments for the DocumentTools:-SetProperty command: the name of the component to update, the property to update, the new value for that property, and an optional parameter to indicate whether the update occurs immediately.

Code associated with a component can perform many different tasks. In particular, it can update other components. For example, you can create a plot component that returns certain values displayed in TextArea components or makes changes to other plots when the plot component is clicked.

When code is run as a result of a mouse event that updates other components, those updates occur after that code runs successfully. While this process is efficient, in some cases, you might want these updates to occur immediately. In such cases, you can use the optional refresh = true parameter, or simply refresh.

The DocumentTools:-Do command is a convenient interface to both the DocumentTools:-GetProperty and DocumentTools:-SetProperty commands. Components can be referenced as variables in expressions. For example, suppose that you have a math container component, two text area components, a button, and a plot component. You can enter a math expression in the variable x in the math container, numbers in each of the text areas and click the button, causing the expression to be plotted over the range specified by the numbers. Assuming the components that you inserted in your document are named MathContainer0, TextArea0, TextArea1, Button0, and Plot0, respectively, you can accomplish this task by using the single command DocumentTools:-Do( %Plot0 = plot( %MathContainer0, 'x' = %TextArea0 .. %TextArea1 ) ).

Consider the following points when deciding whether to use the DocumentTools:-Do command to retrieve or update components.

A layout manager defines the locations and positions of the UI elements in a Maplet window. Three layout managers are available.

For simple Maplets, using a layout manager is often sufficient; however, for more complex Maplets, you may need to use multiple layout managers or nest layout managers one inside the other.

Note: For clarity, the full command for each layout control is used in this chapter.

The three layout managers are available in the Maplets,Elements subpackage of the Maplets package. In this chapter, assume that the following command has been run.

This command allows the Maplets:-Elements package commands to be used without prefixing them with Maplets:-Elements:-....

The box layout is the most commonly used layout manager. It is a nested construct of containers where elements can be displayed either horizontally or vertically in the Maplet window. For example,

As shown in the example above, you can use a BoxColumn element to specify a column in a box layout. You can also use a BoxRow element to specify a row in a box layout.

For detailed information about box layouts, refer to the Maplets,Elements,BoxLayout help page.

In a grid layout, all of the elements are displayed in a rectangular grid.

Each grid layout must contain one or more GridRow elements which must, in turn, contain one or more GridCell elements.

Note: Each row or column of the grid is sized according to the maximum height or width of all the elements in that row or column. By default, no spacing is displayed between the largest elements in a grid layout.

The following is a simple example of a grid layout.

For detailed information about grid layouts, refer to the Maplets,Elements,GridLayout help page.

Unlike the other layout managers, the border layout is a container element for other layout managers, though, it can be used for simple Maplets.

Five positions in the layout can be filled: north, south, west, east, and center, each of which has its own layout rules.  See Figure 13.2.

In terms of resizing, north and south extend horizontally, east and west extend vertically, and center extends in both directions.