JADE XAML Developer's Reference - Jade 7

XAML Developer's Reference VERSION 7.0.10

Copyright©2014 Jade Software Corporation Limited. All rights reserved.

Jade Software Corporation Limited cannot accept any financial or other responsibilities that may be the result of your use of this information or software material, including direct, indirect, special or consequential damages, or loss of profits. There are no warranties extended or granted by this document or software material. You should be very careful to ensure that the use of this software material and/or information complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Jade Software Corporation Limited. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Copyright © 2014 Jade Software Corporation Limited. All rights reserved. JADE is a trademark of Jade Software Corporation Limited. All trade names referenced are the service mark, trademark, or registered trademark of the respective manufacturer. For details about other licensing agreements for third-party products, you must read the JADE ReadMe.txt file.

Contents Contents

iii

Before You Begin

vii

Who Should Read this Guide What's Included in this Guide Related Documentation Conventions

vii vii viii viii

Chapter 1 Introduction to JADE XAML

10

Overview XAML Hierarchy JADE XAML Requirements Developing a JADE XAML Application Comparison of the Silverlight Application Types Defining a Silverlight Application JADE Silverlight Stateless Applications JADE Silverlight Stateless Application Definition Components Running a Silverlight Stateless Application Defining the WebSession Class Defining the IIS Environment Generating the XAP and HTML Files for a Silverlight Stateless Application Generation Steps Requirements to Generate XAP and HTML Files Debugging a Silverlight Stateless Application Handling Exceptions in a Silverlight Stateless Application JADE Silverlight Stateful Thin Client Applications Deploying a JADE Silverlight Stateful Thin Client Application Running a JADE Silverlight Stateful Application

Chapter 2 Using the XAML Browser Accessing the XAML Browser Navigating around the XAML Browser Using the XAML Menu Using Function Keys and Shortcut Keys Using Browser Shortcut Keys Caret Movement Shortcut Keys Extending Selected Blocks Shortcut Keys Insert and Delete Shortcut Keys Using the Mouse within the XAML Sheet Using the Mouse within the Line Number Margin Adding a New Document Searching for a Document Editing an Existing Document Using the Edit Menu Undo Command Redo Command Cut Command Copy Command Paste Command Select All Command Find/Replace Command Find Again Command Find At Caret Command Deleting a Document Renaming a Document Refreshing the View Maintaining Properties for Your Document Saving Your Document

XamlDevRef - 7.0.10

10 12 12 14 15 16 17 18 19 22 23 23 25 26 26 26 27 27 28

29 29 32 33 34 34 34 35 35 36 36 36 38 39 40 40 41 41 41 42 42 42 44 44 44 45 46 46 47

XAML Developer's Reference Contents

Save Errors Invalid XAML Parsing Errors Single Quotes in the XAML Comparing the XAML Changes in Parent and Subdocuments Saving Your Document as another Name Generating XAP and HTML Files Selecting the XAML Browser Mode Hiding or Showing the Toolbar

Chapter 3 Painting XAML Documents Using the XAML Painter Accessing the XAML Painter Properties Area of the XAML Painter Expanding or Contracting the View of a Document Painting Area of the XAML Painter XAML Area of the XAML Painter Using Function Keys and Shortcut Keys Creating a XAML Document Adding a New XAML Document Subclassing XAML Controls and Documents Control Subclassing Document Subclassing Adding UI Elements to Your Document Selecting a UI Element Cloning UI Elements Naming a UI Element Adding Container UI Elements Changing the Caption Content of a UI Element Overlapping UI Elements Changing the Runtime Tab Sequence Obtaining Help for a UI Element Defining the Layout of Your XAML Document Sizing Your UI Elements Aligning Your UI Elements Spacing Your UI Elements Options Panel Check Boxes Using Grid Lines to Position UI Elements on XAML Documents Locking the Position of UI Elements on Your Document Direct Select Functionality Previewing UI Elements on Your Document Examples of Laying Out UI Elements Maintaining Properties for Your XAML Document or UI Element Maintaining General Properties Maintaining Size and Position Properties Maintaining Colors and Styling Properties Selecting a Color Maintaining Font Properties Maintaining Grid Definitions Maintaining Miscellaneous Properties Maintaining Transformations Defining Methods for Your Document Saving Your Document Editing an Existing Document in the XAML Painter Using the Keyboard and Mouse to Edit Your Document Selecting Multiple UI Elements Changing the Size of Selected UI Elements Moving UI Elements around Your Document Copying UI Elements

XamlDevRef - 7.0.10

iv

48 49 50 50 51 52 53 54 54

56 56 57 59 61 62 62 63 64 65 67 67 67 68 69 70 71 71 72 73 74 74 74 75 76 76 77 77 78 78 79 80 81 82 83 83 84 86 86 87 88 89 89 89 90 90 91 91 91


Displaying the Properties for a UI Element Placing a UI Element on a Container UI Element Removing a UI Element from Your Document Changing a UI Element Type Effects of Editing an Existing Document Deleting a Document Layout Toolbar Align Bottom Button Align Top Button Align Left Button Align Right Button Vertically Adjacent Button Horizontally Adjacent Button Align Centers Vertically Button Align Centers Horizontally Button Space Evenly Down Button Space Evenly Across Button Same Width Button Same Height Button

Chapter 4 Considerations When Developing Silverlight Applications Using Third-Party Controls Third-Party Control Usage in JADE Silverlight Stateless Applications registerEventHandler Method for DataTemplate Controls Third-Party Control Usage in JADE Silverlight Stateful Applications Abstract Classes and Third-Party Controls Accessing .NET Objects Accessing Silverlight Fields and Properties Accessing Silverlight Methods Overloaded .NET Methods Constructors Specifying a Type Enums Using Layout Manager UI Element Types Canvas UI Element Type StackPanel UI Element Type Grid UI Element Type Using the Grid Assistant Grid Assistant Popup Menu Using Resources in XAML Documents Creating Controls Dynamically or from a Template Use of the itemsSource Property by Different XAML Classes XamlSelector and XamlDataGrid Class Use of the itemsSource Property XamlAutoCompleteBox Use of the itemsSource Property Unit Testing Silverlight Applications Adding Silverlight Unit Tests to the JADE Unit Testing Framework Configuring a Silverlight Stateful Application to Run Unit Tests Configuring a Silverlight Stateless Application to Run Unit Tests Running the Silverlight Application Unit Tests Viewing Failed and Ignored Tests Testing the Behavior of Silverlight UI Elements

Appendix A Silverlight Terms and Frequently Asked Questions (FAQs) Brush Border Panel Text Boxes and Similar Controls Content Control

XamlDevRef - 7.0.10

v

91 91 92 92 93 93 93 94 95 95 95 95 96 96 96 96 97 97 97

98 98 98 100 101 101 102 102 102 102 103 103 103 104 105 105 106 110 112 113 114 115 115 116 117 117 119 119 121 122 124

128 128 128 128 129 129


Scroll Viewer Tab Control and Tab Item Button, Toggle Button, Radio Button, and Check Box Items Control Shapes Frequently Asked Questions How do I load the contents of a combo box or list box with strings? How do I load the contents of a combo box or list box with an image and a string? How do set the caption of a button? How do I set an image in a button? How do I create a layout where the controls automatically resize when the browser resizes? How do I set the background brush of an element in JADE logic to be a solid color, a linear image, an image, or to use a gradient? How can I use logic to change the way the border of a control is presented? What XAML UI element is most similar to the classical UI Table class, and how do I populate it? How do I control which document is shown to the user? How can I rotate text? How can I dynamically draw on a window? How do I create and use a splitter? How do I set up radio buttons in Silverlight? What is the difference between the various types of panels and how do I use them? How do I set the contents of a label in Silverlight? How do I set up and control a scrollable item in Silverlight? How do I use a calendar control in Silverlight? How do I use the date picker control in Silverlight? How do create a password field in Silverlight? What is the XamlRangeBase class and where would I use it? How do I control a progress bar in Silverlight? Is there an equivalent control to the busyIndicator in Silverlight? How do I detect that the Silverlight equivalent of a Folder control has changed sheets? How do I set up a hierarchical list box? What is XamlTabItem and how do I use it? How do I set up and use a hyperlink button? How do I specify an image and a label divided by 10 pixels as a content of a button? How do I resize the following scenario if somebody resizes the browser?

XamlDevRef - 7.0.10

vi

129 129 130 130 130 130 130 130 131 131 131 132 132 133 134 134 134 134 135 135 136 136 136 136 137 137 137 137 137 138 138 138 138 139

Before You Begin

The JADE XAML Developer’s Reference is intended as the main source of information when you are developing or maintaining JADE applications using the Extensible Application Markup Language (XAML). This document provides reference to JADE's XAML classes, which are wrapper classes for Microsoft Silverlight functionality. Much of the documentation for these classes has been sourced from Microsoft's Developer Network Library Web site, available at: http://msdn.microsoft.com/en-us/library/default.aspx Copyright of this material remains with Microsoft Corporation.

Who Should Read this Guide The main audience for the JADE XAML Developer’s Reference is expected to be developers of JADE application software products using XAML.

What's Included in this Guide The JADE XAML Developer’s Reference has four chapters and one appendix. Chapter 1

Provides an overview of JADE XAML

Chapter 2

Provides instructions for using the XAML Browser

Chapter 3

Provides instructions about using the XAML Painter to paint XAML documents

Chapter 4

Provides details about considerations when developing a Silverlight application

Appendix A

Provides Frequently Asked Questions (FAQs) and an overview of JADE XAML terminology

Example Resources The JADE examples download contains the following example resources. XamlStatelessSchema, which is a stateless example of the Erewhon system. This requires the standard Erewhon schemas to be installed. SilverlightBasic, which is a testing resource that includes an example of the handling of every type of XamlUIElement, their properties, methods, and events. In addition, it includes subclass handling. The XamlStatelessSchema (and other Silverlight examples) are available from the following URL. http://www.jade.co.nz/downloads/jade/schemas/JADE_Examples.zip After you have unzipped and installed the JADE_Examples.zip file, the example schemas and the JADE Erewhon Silverlight Guide are located in examples/Silverlight/examples of your JADE directory.

XamlDevRef - 7.0.10

XAML Developer's Reference Before You Begin

viii

Related Documentation Other documents that are referred to in this guide, or that may be helpful, are listed in the following table, with an indication of the JADE operation or tasks to which they relate. Title

Related to…

JADE Encyclopaedia of XAML Classes

Extensible Application Markup Language (XAML) classes

JADE Initialization File Reference

Maintaining JADE initialization file parameter values

JADE Installation and Configuration Guide

Installing and configuring JADE

JADE Platform Differences Guide

Platform differences when running JADE applications

JADE Development Environment User’s Guide

Using the JADE development environment

JADE Thin Client Guide

Administering JADE thin client environments

JADE Web Application Guide

Implementing, monitoring, and configuring Web applications

Conventions The JADE XAML Developer’s Reference uses consistent typographic conventions throughout. Convention

Description

Arrow bullet ( )

Step-by-step procedures. You can complete procedural instructions by using either the mouse or the keyboard.

Bold

Items that must be typed exactly as shown. For example, if instructed to type foreach, type all the bold characters exactly as they are printed. File, class, primitive type, method, and property names, menu commands, and dialog controls are also shown in bold type, as well as literal values stored, tested for, and sent by JADE instructions.

Italic

Parameter values or placeholders for information that must be provided; for example, if instructed to enter class-name, type the actual name of the class instead of the word or words shown in italic type. Italic type also signals a new term. An explanation accompanies the italicized type. Document titles and status and error messages are also shown in italic type.

Blue text

Enables you to click anywhere on the cross-reference text (the cursor symbol changes from an open hand to a hand with the index finger extended) to take you straight to that topic. For example, click on the "What's Included in this Guide" cross-reference to display that topic.

Bracket symbols ( [ ] )

Indicate optional items.

Vertical bar ( | )

Separates alternative items.

Monospaced font

Syntax, code examples, and error and status message text.

ALL CAPITALS

Directory names, commands, and acronyms.

SMALL CAPITALS

Keyboard keys.

XamlDevRef - 7.0.10

XAML Developer's Reference Before You Begin

ix

Key combinations and key sequences appear as follows. Convention

Description

KEY1+KEY2

Press and hold down the first key and then press the second key. For example, "press SHIFT+F2" means to press and hold down the SHIFT key and press the F2 key. Then release both keys.

KEY1,KEY2

Press and release the first key, then press and release the second key. For example, "press ALT+F,X" means to hold down the ALT key, press the F key, and then release both keys before pressing and releasing the X key.

In this document, the term Microsoft Windows refers to Windows 8, Windows 7, Windows Server 2012, Windows Server 2008, Windows Vista, or Windows Mobile. When there are differences between the versions of Microsoft Windows, the specific version of Microsoft Windows is stated. With the exception of the jade.exe program, when referring to program executables in this document, the .exe file suffix is omitted; for example, jadclient refers to jadclient.exe. Similarly, the .dll (Dynamic Link Library) suffix is omitted. For example, jomos refers to jomos.dll.

XamlDevRef - 7.0.10

Chapter 1

Introduction to JADE XAML

This chapter covers the following topics. Overview XAML Hierarchy JADE XAML Requirements Developing a JADE XAML Application Comparison of the Silverlight Application Types Defining a Silverlight Application JADE Silverlight Stateful Thin Client Applications Deploying a JADE Silverlight Stateful Thin Client Application Running a JADE Silverlight Stateful Application JADE Silverlight Stateless Applications JADE Silverlight Stateless Application Definition Components Running a Silverlight Stateless Application Generating the XAP and HTML Files for a Silverlight Stateless Application Debugging a Silverlight Stateless Application Handling Exceptions in a Silverlight Stateless Application

Overview In this chapter, the term XAML indicates the Silverlight Extensible Application Markup Language (XAML) implementation. For details about XAML terminology, see Appendix A. JADE XAML enables you to create rich Web applications that run on Windows; that is, you can develop applications that run in a browser and that use the Microsoft Silverlight presentation facilities.

Note Silverlight does not run in a 64-bit mode or from a 64-bit thin client. As Microsoft does not yet support Silverlight in the 64-bit version, the XAML Browser or XAML Painter requires a 32-bit presentation client JADE version. User interfaces in XAML applications are: Declared in the Windows Presentation Foundation (WPF) Extensible Application Markup Language (XAML). Programmed using a subset of the .NET framework. Textual content created with XAML can be searched and indexed by search engines, because it is represented as XAML text rather than being compiled. The XAML Browser and XAML Painter JADE Silverlight applications enable you to define user interfaces in XAML. For details, see "Using the XAML Browser", in Chapter 2, and "Using the XAML Painter", in Chapter 3.

XamlDevRef - 7.0.10

XAML Developer's Reference Chapter 1 Introduction to JADE XAML

11

Microsoft Silverlight is a browser plug-in similar to Adobe Flash. Silverlight must be installed on the client computer (that is, the computer that will be using a Web browser). It can be downloaded from Microsoft. For details, see "JADE XAML Requirements", later in this chapter. A normal HyperText Markup Language (HTML) page is used to host the XAML User Interface (UI) element. An tag with various information about the XAML application being referenced is present in an HTML page. Microsoft recommends that certain other HTML tags and JavaScript routines are present in this HTML file. Depending on the Silverlight application type, JADE generates a skeleton HTML file automatically or on request, with the user XAML application embedded that conforms to these requirements. You can then alter this HTML file to meet your requirements. By default, the XAML application encompasses the entirety of the page, or document; however, it may be confined to any arbitrary region of the page. A Microsoft Silverlight application has the .xap suffix (XAML Application). You can define the following types of Silverlight-based applications in JADE. A stateless Web services-like version, where all presentation layout and logic handling is executed in the browser and requires no communication with the JADE client (standard client or application server). Communication to the JADE system that performs the associated database logic is via Microsoft Internet Information Server or Apache Web Server (hereafter referred to as IIS). One or more copies of the JADE application process the requests for all users. A Silverlight stateless application consists of the definition of: The presentation handling that runs entirely in the browser. The JADE logic that provides access to the database layer that runs in a standard or application server client. Classes and methods that provide the communication between the two components. Any transient objects that are created in user code should be deleted when they are no longer required. The only data that can be retained between requests is that data stored on the WebSession object, if that feature is configured. For details, see "Defining the WebSession Class", later in this chapter. The JADE presentation code is translated into equivalent Silverlight C# code and compiled into a runtime Silverlight Application (.xap) module that is loaded by the browser when the application HTML link is selected in the browser by the user. The JadeAgl.xap file module handles the initiation process, the configuration requirements, the packaging and un-packaging of non-browser method requests, and communication with IIS via a URL that is specified in the HTML file. A thin client-based version, where all JADE logic runs in the application server and communication to the browser hosting the content is performed via a dedicated TCP/IP connection from the workstation of the user. A JADE Process instance is used by every connected user and the application session retains the current state of transient objects over subsequent transmissions from the browser. This mode of operation is referred to as the stateful mode. Every logic reference to Silverlight GUI properties and methods is sent from the application server to the browser in the client’s PC. These result in a significant increase in the amount of network traffic compared to standard thin client JADE, because the application server has no local knowledge of GUI property values. As a result, this type of application is probably suitable only for use over a fast LAN network.

XamlDevRef - 7.0.10


12

As the JADE XAML presentation client is contained in the JadeAgl.xap file, your HTML files should reference this file. This XAML application acts as the JADE presentation client, communicating with the JADE application server and running the user JADE application. The architecture is similar to the traditional JADE presentation client, but instead of jade.exe being used as the presentation client, JadeAgl.xap runs inside the Web browser and acts as the presentation client. For details, see "Comparison of the Silverlight Application Types" and "Defining a Silverlight Application", later in this chapter. In this document, an HTML file is referred to as an HTML document and the presentation of that file on a Web browser at run time is referred to as an HTML page.

XAML Hierarchy The XAML control hierarchy is located under the XamlObject class, which is inherited from the RootSchema Object class. For details about XAML classes and properties, see your JADE Encyclopaedia of XAML Classes. Additional details are available from the following URL. http://msdn.microsoft.com/en-us/library/cc838158(VS.95).aspx

Note Classes marked abstract in the previous hierarchies are abstract in Silverlight and you cannot create them. However, as they are not abstract in JADE, when an instance of a third-party control is created, its parent hierarchy is traversed until a matching RootSchema class is found (for example, XamlUIElement) and an instance of that class is returned.

JADE XAML Requirements JADE XAML requires the Microsoft Silverlight 4 plug-in, which you can download from http://www.microsoft.com/silverlight/get-started/install/default.aspx, to be installed on presentation clients. The following files must be installed in the bin directory of your application server. File

Required for…

JadeAgl.xap

JADE presentation clients

JadpmapSL.dll

JADE application server extension

XamlPainter.xap

XAML Painter

AglPreview.xap

JADE previewer

The AglPreview.xap, XamlPainter.xap, and JadeAgl.xap files do not need to be present on the presentation client. When you initiate the XAML Painter or XAML Browser from the JADE development environment, the XAP files are copied from the application server to the temporary directory on the presentation client prior to initiation of these applications. In addition, when you initiate the XAML Painter, a jadeXamlPainter.html file is dynamically created on the application server and then copied the temporary directory on the presentation client. These files are required during development of Silverlight applications. At run time, only the presentation client JadeAgl.xap file and the application server extension JadpmapSL.dll file are required.

XamlDevRef - 7.0.10


13

When a Silverlight application is initiated from the JADE development environment, the HTML file used to initiate the application is dynamically generated and written to the temporary directory on the presentation client prior to initiation of the application. You can define your own HTML file to be used for Silverlight application initiation by setting the HtmlFile parameter in the [JadeSilverlight] section of the JADE initialization file on the application server. The HtmlFile parameter specifies the location of the HTML file to be used when the JADE XAML Painter is opened or a Silverlight application is run from the JADE development environment. The default parameter value is , which means that JADE generates an HTML file from the internally stored definition. Specify a value other than null or , to specify the location of the HTML file to be used. This parameter enables you to control the contents of the HTML. However, it must have a section of where JADE will insert the initiation parameters required to start the Silverlight application, as shown in the following example. [JadeSilverlight] HtmlFile=c:\JADE\Silverlightdefault.html If the HtmlFile parameter is specified, the Silverlight element must contain the following element that contains initParams values required to connect to the JADE application server and run an application. Any parameter specified other than App, Schema, AppServer, and AppServerPort is retained.

Notes To run a Silverlight stateless application, you must first generate the required XAP and HTML files. For details, see "Generating the XAP and HTML Files for a Silverlight Stateless Application", later in this chapter. A JADE Silverlight stateful thin client application server must be run on a port number in the range of 4502 through 4534. This limitation is imposed by Microsoft, as TCP/IP connections from Silverlight applications back to the Web server are allowed only in this range. If a document is not defined for the current locale of your presentation client, the XAML Painter does not try to use another locale, which is usually the default locale; that is, English (New Zealand). The XAML Browser previews a document and loads its XAML only if there is XAML for your current (system) locale. You must therefore set your base locale (for example, select English (New Zealand) in the Base Locale combo box on the Miscellaneous sheet of the Preferences dialog) so that the XAML for your base locale can be located, the XAML loaded, and the document previewed and displayed in the XAML Painter. By default, a Silverlight presentation client sends and receives unencrypted data over the TCP/IP connection to the application server. As Silverlight does not support Secure Sockets Layer (SSL)-style encryption for TCP/IP, it is not available for JADE use. You can enable encryption for all Silverlight presentation clients connecting to an application server by setting the TcpEncryptionType parameter in the [JadeSilverlight] section of the JADE initialization file on the application server, as shown in the following example. [JadeSilverlight] TcpEncryptionType=aes-128 The aes-128 value enables 128-bit Advanced Encryption Standard (AES) encryption using private/public key exchange. A jommsg.log entry is generated confirming that encryption is in use. The other valid values are none (the default value) or empty (blank), meaning no encryption is required. Any other value reports an error and a value of none is assumed.

XamlDevRef - 7.0.10


14

Developing a JADE XAML Application When developing a JADE XAML application, you paint pages, or documents, that become subclasses of the XamlDocument class. The XamlDocument class is the Silverlight equivalent of the Form class in the classical JADE development environment. Form classes have references to controls, and those controls have events and event logic defined on them. This process is the same with the JADE Silverlight GUI except that you use different classes. XAML documents have references to User Interface (UI) elements, which have properties, events, and event logic defined on them. For an overview of User Interface (UI) element terminology, see Appendix A. The XamlDocument control subclasses are in the RootSchema hierarchy under the XamlUIElement class. (See also "XAML Hierarchy", earlier in this chapter.) HTML is a useful way of specifying graphical controls in XML. In a similar manner to HTML, Silverlight applications use Extensible Application Markup Language (XAML) to specify graphical controls UI elements. Although the JADE XAML Painter provides a What You See Is What You Get (WYSIWYG) interface, it is simply dealing with an underlying piece of XAML. Each XamlDocument subclass in JADE is essentially a piece of XAML; that is, text in Extensible Markup Language (XML) format, which you can access and edit directly through the JADE XAML Painter. (For details, see Chapter 3, "Painting XAML Documents".) This enables you to copy the XAML to third-party painters and tools and then import them back into JADE; for example, when defining complex animations or graphics in XAML beyond the scope of the XAML Painter. To create a JADE XAML application, you require the following components. 1.

Using the XAML Browser or the XAML Painter, or both the XAML Browser and the XAML Painter, define the Silverlight documents that make up the pages that will be displayed to the user in the browser.

2.

Using the JADE development environment, define the event methods that format and process the user actions required on those documents.

For additional details about developing a Silverlight stateless application, see "JADE Silverlight Stateless Application Definition Components", later in this chapter. When developing a XAML application: The debugger functions normally. For details, see "Debugging a Silverlight Stateless Application", later in this chapter. Although you can use app.msgBox as normal, its flags support only Okay, Cancel, Yes, and No buttons.

Note You can use app.msgBox in stateful (thin client) mode and in stateless mode. The write statement works normally when the application is run from the JADE development environment, but when you deploy and run a XAML application from outside of the JADE development environment, it writes to Silverlight Isolated Storage, which is a hard-to-locate directory on the presentation client that Silverlight uses to store application information. When you develop a XAML application using Silverlight: Stateless mode, XAML JADE methods defined with the webServerExecution method option indicate a method that transfers control from a browser back to JADE code via the implied Web service. Thin client mode, XAML JADE methods defined with the browserExecution method option are converted to C# code and the compiled code is downloaded to the Silverlight client. This enables you to minimize network traffic by performing specific user interface-related operations without requiring trips to the application server.

XamlDevRef - 7.0.10


15

An exception is raised when you specify the webServerExecution or browserExecution method option in a method defined in a class that is not allowed for stateless or presentation client Silverlight processing, respectively.

Comparison of the Silverlight Application Types The following table compares the Silverlight presentation client-based and Silverlight stateless application types. Silverlight Presentation Client

Silverlight Stateless

A JADE process is required for each user session.

One or more copies of the JADE process are used by all connection clients.

Requires an application server.

A standard JADE client or an application server can be used.

Communication from the browser to the JADE process is via a dedicated TCP/IP connection.

Communication from the browser is via the standard Internet services using IIS or Apache.

Network security is via Advanced Encryption Standard 128

Standard browser network security via HTTPS (SSL). routines.

Stateful. All transient objects created are retained and are available during the application session.

Stateless. No transient object created can be retained and reused between requests sent to the JADE client. Web session handling can be enabled, which provides the ability to store data persistently on the WebSession object.

All JADE logic is executed in the application server. Any reference to presentation objects requires a transmission from the application server to the browser.

Presentation logic is executed entirely in the browser. No communication to the JADE client is required to perform these functions. All database logic is executed in the JADE client.

Not as scalable. An application server can support only a limited number of clients. To support more clients, more application servers are required.

Scalable. The support of more clients requires only the initiation of more copies of the application.

Uses the standard JADE environment only.

Uses the standard JADE environment. For the generation of the presentation module, Microsoft Visual Web Developer 2010 Express and Microsoft Silverlight 4 Tools for Visual Studio 2010 must be installed.

No generation of the run time environment is required.

Generation of the presentation layer is required. No generation of the JADE client application module is required.

JADE logic changes take immediate effect.

JADE logic changes to the JADE client module take immediate effect. Changes to the presentation layout and logic require re-generation and deployment of the presentation module.

Standard JADE debugging is available.

Standard JADE debugging is available for the JADE client module. Debugging the presentation module can be done only by running a presentation client-defined version of the application.

XamlDevRef - 7.0.10


16

Defining a Silverlight Application To run a XAML application, use the Define Application dialog to specify the Silverlight application type, which can be Silverlight (for a stateful thin client application), or Silverlight Stateless, Gui or Silverlight Stateless, Non-GUI (for a stateless application). For details about the Application sheet of the Define Application dialog, see "Defining Applications", in Chapter 3 of the JADE Development Environment User’s Guide. To define a XAML application 1.

In the Application Type combo box, select one of the following values. Silverlight, to specify a presentation client-based JADE XAML application. Silverlight Stateless, GUI, to specify a stateless Web services-like JADE XAML application, which creates the standard Web Monitor dialog that displays all received requests. Silverlight Stateless, Non-GUI, to specify a stateless Web services-like JADE XAML application, which does not create the standard Web Monitor dialog.

Notes The Silverlight Stateless, Non-GUI application type terminates only after the JADE terminate instruction is executed. The Application class startApplication and startAppMethod methods start only Silverlight Stateless, Non-GUI applications if they are invoked from a server method or server application. (An exception is raised if they are invoked from a server method or a server application to start an application of a type other than non-GUI.) On a client node, they start all types of application. Running a JadeScript method when the currently selected application type is Silverlight or Silverlight Stateless, GUI changes the application type to GUI for the execution of that method. 2.

In the Startup XAML combo box, select the XAML document that is to be displayed on start up.

3.

If you are defining a Silverlight stateless application, select the initialize and finalize methods to be run by the JADE client logic when the application is initiated. These do not apply to the presentation browser-based module. Use the start-up document create method for any initialize logic that needs to be run initially in the browser.

4.

If you are defining a Silverlight stateless application, on the Web Options sheet, define: a.

The connection name and port that is used by the server application to connect to the JadeHttp.dll via TCP/IP; for example, localhost:20002.

b.

The number of the application copies to be initiated.

c.

The session timeout value if sessions are enabled (for details, see the following section).

d.

The scheme being used; that is, http or https (SSL).

e.

The machine name to which the browser is to connect.

f.

XamlDevRef - 7.0.10

The IIS virtual directory where the HTML and XAP files are located.


5.

17

When you have saved your specified application values and clicked the OK button on the Define Application dialog, select the: XAML Painter command from the File menu, to open the XAML Painter and create a new document. For details, see Chapter 3, "Painting XAML Documents". XAML Browser command from the File menu, to open the XAML Browser; for example, if you want to navigate to or preview an existing document. For details, see "Accessing the XAML Browser", in Chapter 2.

When you have created the new document class, you can edit the document. (There will be some basic XAML sitting in the document, based on the type of document that you specified.)

JADE Silverlight Stateless Applications A JADE Silverlight stateless application is defined entirely in JADE and consists of: The XAML documents that will be displayed to the user. Methods to format and present XAML documents and handle GUI events. This logic is executed entirely in the browser and these methods must have browserExecution in their signature and must be marked as being browserExecution. No GUI manipulation can be performed by JADE client logic; only by browserExecution logic. In addition to primitive types and primitive type arrays, only a specific list of classes and their subclasses can use browserExecution in their method signatures. These classes are: XamlDocument XamlObject XamlManager XamlDataObject XamlDataObjectArray XamlDataObjectDictionary Application For details, see "browserExecution Option", in Chapter 1 of the JADE Developer’s Reference. When a class is extracted for the generation of the XAP file, only attributes (other than MemoryAddress attributes) and references of these types are extracted. All other properties are dropped from the class and are not available in the Silverlight stateless version of the class. The value of a constant is extracted (instead of the source) when JADE generates the XAP file, so constants that are not extracted do not cause a problem. To use constants that are defined on classes that are not extracted for a Silverlight stateless application, redefine the constants on a class that is valid in Silverlight in terms of the other (non-extracted) constant. For example: Define the constant on the class NotExtracted as: NotExtractedConst:Integer=123;

XamlDevRef - 7.0.10


18

Define the constant on the class IsExtracted as: NotExtractedConst:Integer=NotExtracted.NotExtractedConst; Note that the JADE compiler will check that in a browserExecution method, references are made only to: Other browserExecution methods webServerExecution methods on XamlDataObject subclasses in a stateless environment A restricted set of classes, properties, and methods in the RootSchema that are marked as allowBrowserExecution The only global class that can be referenced is the Application class. Application class property values are local only to where they are being referenced and they are not automatically transferred between the two modules. Global, Iterator, WebSession, Process, Node, and meta data (for example, Class) class references are not permitted. When a class is extracted for the generation of the XAP file, only properties of these types are extracted. Any other properties are dropped from the class and are not available in the Silverlight version of the class. You should not use properties of these classes if you intend to use the class in a stateless runtime operation. JADE methods that will be remotely called from the browser. These are methods marked as webServerExecution and are referenced in browserExecution methods. For details, see "webServerExecution Option", in Chapter 1 of the JADE Developer’s Reference. These methods, which can be defined only on subclasses of XamlDataObject, can pass only parameters and a return type of the following types. Primitives (including primitive arrays) Subclasses of XamlDataObject Subclasses of XamlDataObjectArray Subclasses of XamlDataObjectDictionary (dictionaries can have one key only) These parameters can be usage IO, input, or output. The browser logic is always the initiator of any communication between the browser and the JADE client. This communication always takes the form of one message out from the browser and one message in reply from the JADE client. Standard JADE logic associated with database access and update, called from the webServerExecution methods described in the previous item in this list.

JADE Silverlight Stateless Application Definition Components To create a Silverlight stateless application, you require the following components. 1.

Using the XAML Browser or the XAML Painter, or both the XAML Browser and the XAML Painter, define the Silverlight documents that make up the documents that will be displayed to the user in the browser.

2.

Define the event methods that format and process the user actions required on those documents. These methods must be marked as being browserExecution. No GUI manipulation can be performed by JADE client logic; only by browserExecution logic.

XamlDevRef - 7.0.10


19

Notes You can subclass XamlUIElement classes and define event methods on those subclasses. When such a method is present and the associated event is called, that method is called first and when that method calls inheritMethod, the event method associated with the actual UIElement on the document is called. For example, if MyXamlButton is a subclass of XamlButton and has implemented the click event, clicking a button of that type (for example, btnOK) calls the MyXamlButton::click method and when inheritMethod is called, the btnOK_click method is called. Some browsers (for example, Mozilla and Chrome) allow additional events to be processed and cause the presentation to be repainted when a request to IIS is outstanding. For this reason, when an IIS request is outstanding, mouse events are disabled and key events are discarded so that the user cannot affect the presentation until the current actions are completed. This browser behavior can result in simultaneous requests being made to IIS. For example, if a document is loaded where multiple elements implement a loaded event that references webServerExecution methods, each loaded event will effectively be sent to IIS simultaneously. 3.

Define the subclasses of XamlDataObject for objects that will be passed to and returned from JADE webServerExecution methods.

4.

Define the JADE methods that will be remotely called from the browser. These are methods marked as webServerExecution and are referenced in browserExecution methods. These methods, which can be defined only on subclasses of XamlDataObject, can pass only parameters and a return type of the following types. Primitives (including primitive arrays) Subclasses of primitive arrays (for example, StringArray, StringUtf8Array, IntegerArray) Subclasses of XamlDataObject Subclasses of XamlDataObjectArray Subclasses of XamlDataObjectDictionary (dictionaries can have one key only) These parameters can be usage IO, input, or output. The browser logic is always the initiator of any communication between the browser and the JADE client. This communication always takes the form of one message out from the browser and one message in reply from the JADE client. These methods will pass the contents of the object on which the call is made, together with any parameters and any references to other objects defined. When the method returns, the content of the object on which the call was made is updated, together with any usage IO or output parameters. These methods: Must delete any transient objects created, other than those passed back Can reference any object defined within the JADE application except for any XamlDocument, XamlObject, or XamlManager classes

Running a Silverlight Stateless Application You cannot run a Silverlight stateless application in the JADE development environment. To do so, you must create another application definition that is of Silverlight presentation client style; for example, to debug the application (for details, see "Debugging a Silverlight Stateless Application", later in this chapter).

XamlDevRef - 7.0.10


20

The following diagram is a depiction of the various parts of the Silverlight stateless runtime environment.

To configure the runtime environment for Silverlight stateless applications, the following components are required, after you have specified the stateless application. To run a Silverlight stateless application 1.

Configure the IIS or Apache Web Server environment in the same way that a Web service environment is defined. For details, see "Web Server Setup", in the Web Services Tips and Techniques white paper (available from http://www.jade.co.nz/jade/whitepapers.htm), and "Defining the WebSession Class" and the IIS definition example under "Defining the IIS Environment", later in this chapter.

Note When you define the default values for your application pool, ensure that the Enable 32-Bit Applications option is set to False on the Application Pool Defaults dialog, as this is the correct setting for a 64-bit jadehttp.dll. 2.

Copy the generated XAP and HTML files into the IIS virtual directory that is being used. For details about generating XAP and HTML files, see "Generating the XAP and HTML Files for a Silverlight Stateless Application", later in this chapter.

3.

Initiate the JADE application, ready to process requests from the users.

4.

Click on a link to the HTML file that describes the application environment to be initiated. For Microsoft security reasons, this link must be an HTTP or HTTPS link (SSL encryption) so that the domain in that link is the same domain used to obtain the XAP file. This HTML file is created by the JADE development environment during the generation process that is described under "Generating the XAP and HTML Files for a Silverlight Stateless Application", later in this chapter.

5.

The browser processes the HTML file and then loads the XAP file from IIS that contains the modules required to be executed in the browser. This XAP file is generated by the JADE development environment. The logic loads and displays the start-up document defined on the JADE application.

XamlDevRef - 7.0.10


21

Note Browsers usually cache the XAP file, which will be downloaded again only when it is recognized as being different. 6.

When the browser logic encounters a remote method call (a webServerExecution method), a call is made to IIS, passing the receiver object together with all of the parameter values. The method calling the webServerExecution method could be, for example, the create method of the document or an event defined on the document such as the loaded event of an element or the click event of a button. In the following example of such a method, ShopOperator is a subclass of XamlDataObject and the getAllOperators method is a webServerExecution method. cmbLogonUser_loaded(control: XamlComboBox input; originalSource: XamlObject input) browserExecution, updating; vars operators : StringArray; shop : ShopOperator; begin create shop transient; operators := shop.getAllOperators(); cmbLogonUser.itemsSource := operators; epilog delete shop; end;

7.

When IIS receives the request, it passes it to JadeHttp, which in turn passes the message to a copy of the JADE application, using the rules defined for Web services.

8.

When the JADE application receives the request, it automatically creates a transient copy of the object that is the receiver of the method to be called and any object parameters (and recursively, any references defined on those objects).

9.

The JADE application then calls the requested method on the created object. That method performs the JADE logic associated with that action. For example: getAllOperators(): StringArray webServerExecution; vars client : Client; company : Company; result : StringArray; begin company := Company.firstInstance; if company null then create result transient; foreach client in company.allClients do result.add(client.name); endforeach; endif; return result; end;

10.

When the method completes, the updated contents of the object on which the method was called are passed back to the browser, together with any parameters that were usage IO or output and the method’s return value data.

XamlDevRef - 7.0.10


22

All transient objects created automatically in the JADE client are then deleted. It is your responsibility to ensure that any other transient objects created during the execution of the JADE logic are also deleted. 11.

When the reply is received in the browser logic, the objects passed back are updated and the current method logic then continues its execution.

Defining the WebSession Class If Web session handling is not enabled, currentSession will be null in JADE logic. If Web session handling is enabled, a unique instance of the schema WebSession subclass is created for each user and currentSession is set to that instance before the requested webServerExecution method is called. JADE logic can use this object to retain some state information for each user. To enable Web session handling, use the JadeMonitorSchema schema JadeWebConfigurator application to build the HTML file that defines the Web environment values. For details about configuring a Web application, see Chapter 3 of the JADE Web Application Guide. Use of this file overrides application-defined parameters. In particular, ensure that the application/web_ config/web_services_provider/use_session_handling option is set to true. Set the ApplicationConfigFile parameter value in the [WebOptions] section of the JADE initialization file to the file being used; for example: [WebOptions] ApplicationConfigFile=G:\JADE\SilverlightBasic\SilverlightStatelessConfig.xml A sample configuration is as follows. localhost:20010 5 10 0 false 0 c:\temp\webactivity.log false 1 true false http localhost JADE

XamlDevRef - 7.0.10


23

0 true false 1 1 0 0 0

Note The WebSession object for each user is a persistent object that can be updated only in transaction state.

Defining the IIS Environment Define the IIS environment as you would for a Web service application. This includes the requirement that the jadehttp.ini file contains the definition required for this application, as shown in the following example. [SilverlightStatelessApp] ApplicationType=WebServices TcpConnection=localhost TcpPort=20010 connectionGroup= MinInuse=1 MaxInuse=15 CloseDelay=10 MaxMessageSize=1000000 MinMessageSize=5 MessageTimeout=300 VirtualDirectory= MaxQueueDepth=0 GroupSharesConnections=false

Generating the XAP and HTML Files for a Silverlight Stateless Application You must create a Silverlight Stateless, Non-GUI or a Silverlight Stateless, Gui application type for your schema before you can generate the XAP and HTML files for that application. For details, see "Defining a Silverlight Application", earlier in this chapter.

XamlDevRef - 7.0.10


24

The generate (XAP build) process uses the following information. 1.

The JADE application definition.

2.

The names that you supplied for the XAP and HTML files. By default, these are taken from the application name.

3.

The output directory that you specified, which defines where the generated XAP and HTML files are placed at the end of a successful build. This directory name is retained in the [JadeSilverlight] section of the JADE initialization file.

Generate the XAP and HTML files for your Silverlight stateless application in the following ways. Using the jadclient command line (for details, see "Running a Non-GUI Client Application using jadclient", in Chapter 1 of the JADE Runtime Application Guide) From the JADE development environment You must regenerate and redeploy the files each time you make changes to the presentation layout and logic of the Silverlight stateless application. For details about generating the XAP and HTML from the JADE development environment in the XAML Browser, see "Generating XAP and HTML Files", in Chapter 2. For details about the machine requirements, see "Requirements to Generate XAP and HTML Files", later in this chapter. When using the jadclient command line, run the XapFileBuilder JADE schema application and provide the following parameters (in the specified order). 1.

Schema name

2.

Application name

3.

XAP file name

4.

HTML file name

5.

Results directory name (the directory name is retained in the [JadeSilverlight] section of the JADE initialization file)

6.

Whether the temporary build directory is retained

The following is an example of using the jadclient command line to generate the files. jadclient path=c:\mySystem ini=c:\mySystem\JADE.ini schema=JadeSchema app=XapFileBuilder endJADE MySilverlightSchema MySilverlightApplication MySilverlightApp StartupPage c:\website\bin true The generate is performed on the client node (that is, the standard JADE client or the application server, when running in presentation client mode). In Silverlight thin client mode, the XAP file is always built on the application server, in the JADE work directory of that node. However if the build does not complete successfully, the log files are copied to the location specified by the XapBuildLogDirectory parameter in the [JadeSilverlight] section of the JADE initialization file (when running in presentation client mode, the JADE initialization file is located on the presentation client and the log files are therefore copied to a location relative to the presentation client). If the value of this parameter is or it is not specified, any log files are copied to the JADE logs directory on the application server. The number of files that is output depends on the phases of the XAP build process that have completed.

XamlDevRef - 7.0.10


25

By default, the build directory is deleted if the generate completes successfully. You can configure the XAP file generate process to retain the build directory, by checking the Retain XAP build directory check box on the XAP File Generator dialog or by specifying true as the last parameter in the jadclient command line. When the XAP file generate process is configured to retain the build directory and the build fails, the build files are copied back to the presentation client (into the location specified by the JadeWorkDirectory parameter on the [JadeEnvironment] section of the JADE initialization file on the presentation client). The files on the application server are still deleted. The name of the retained directory has the following format. JadXAPBuild_user-code_timestamp If you want the retained directory to be written to a constant unique directory, specify UniqueXapBuildDirectory=false in the [JadeSilverlight] section of the JADE initialization file on the presentation client. This excludes the timestamp portion of the file name. However, any contents in any existing directory are overwritten.

Generation Steps After starting, the XAP file generate process: 1.

Extracts browserExecution methods and class definitions.

2.

Generates C# code and project files for extracted methods and classes.

3.

Runs the Microsoft build process over the code generated in the previous step, to build the XAP file.

4.

Generates an HTML page to launch the application.

5.

Copies the XAP and HTML files to the specified location, and deletes all work files and directories, if configured to do so.

As each step is performed, status messages are recorded in various log files. If the generate is successful, these files (which reside in the temporary directory created for the generate) are removed on completion of the build process. If the build fails, the entire temporary directory is retained. A failure is also recorded in the JADE message log (that is, jommsgn.log file). If the build fails, the location of the temporary directory and the XAPbuild.log is reported in a dialog when you run the generate process in the JADE development environment. It is also recorded in the JADE message log, which is useful if you run the generate process from the jadclient program. The XAPbuild.log file lists the steps being performed and whether they were successful. If a step fails, this log file may refer to another log, which may contain more-specific details. When you run the XapFileBuilder application from the jadclient program and the generation fails, the exit code returned is 1; successful generation returns zero (0). Reasons for failure include: Invalid arguments in the XAP build process When a JADE method has not been compiled When a JADE method is in error When a syntax error occurs in the generated C# compile

XamlDevRef - 7.0.10


26

Requirements to Generate XAP and HTML Files The XAP and HTML files are generated on the client node (on the application server when running in thin client mode). The machine on which the client node is running requires the following .NET and Silverlight software to generate the XAP and HTML files used by Silverlight stateless applications. Microsoft Visual Web Developer 2010 Express, which you can obtain from http://www.microsoft.com/express/Downloads/ You can install Microsoft Visual Studio 2010 Professional instead of Microsoft Visual Web Developer 2010 Express. (Microsoft SQL Server is not required to be installed.) Microsoft Silverlight 4 Tools for Visual Studio 2010, which you can obtain from http://go.microsoft.com/fwlink/?LinkID=177428

Debugging a Silverlight Stateless Application To examine the processing of requests received from the browser in the JADE debugger, initiate the application from the Run Application dialog in the JADE development environment and check the Activate Debugger check box.

Note In some browsers (for example, Mozilla and Chrome) some events occur asynchronously and may be directed to application copies that are not being debugged. To avoid this situation, specify 1 in the Application Copies text box on the Web Options sheet of the Define Application dialog and specify >1 in the MaxInUse parameter in the jadehttp.ini file. To debug the presentation client logic, you must create another application definition that is of Silverlight presentation client style. This requires use of an application server to run the application. Initiate this application from the Run Application dialog in the JADE development environment and check the Activate Debugger check box. Under this debugging mode, JADE will create a WebSession object to cover the case where Web session handling is enabled. Debugging in this mode may not be entirely identical to running without debugging, because asynchronous events do not occur, the application mode will be stateful, and the thin client logic for processing GUI properties and methods is different from that used in the stateless mode.

Handling Exceptions in a Silverlight Stateless Application By default, JADE logic exceptions in the JADE client are caught by an internal global exception handler and logged as normal. No exception dialog is displayed. The failure is also reported back to the browser client and displayed in the default exception dialog. Your application could install its own global exception handler, if required. Exceptions that occur in the Silverlight presentation logic running in the browser are displayed to the user, by default. This presentation includes: The name of the method in which the exception occurred. The type of the exception that occurred. The text of the error message. The stack trace of the logic exception. A button that allows the user to copy the information to the clipboard.

XamlDevRef - 7.0.10


27

A button that allows the user to return to the page on which the error occurred and to try again or to perform some other option. JADE enables you to process the exception by re-implementing the Application class handleSilverlightException method (for Silverlight stateless applications), as follows. app.handleSilverlightException(errorNumber: Integer; methodName: String; exceptionType: String; error: String; stackTrace: String): Boolean; The parameters in this method are listed in the following table. Parameter

Description

errorNumber

Error number, if known. This will be non-zero for known situations only; for example, array index out of bounds.

methodName

Name of the method in which the exception occurred. For security reasons, Silverlight does not let logic access the line and column number where the exception occurred.

exceptionType

Name of the exception type (which can be null).

error

Error message text.

stackTrace

Execution method stack at the time of the exception. This can be null if the exception was associated with the inability to connect to the application via IIS.

A return value of true prevents the default exception dialog being displayed. A return value of false displays the default exception dialog.

JADE Silverlight Stateful Thin Client Applications A normal HTML page is used to host the Silverlight control. Inside an HTML page is an tag with various information about the Silverlight application being referenced. Microsoft recommends that some other HTML tags and JavaScript routines are present in this HTML file. On request, JADE automatically generates a skeleton HTML file with the user Silverlight application embedded that conforms to these requirements. You can then extend or alter this HTML file, to meet the requirements of your Web site. By default, the Silverlight application encompasses the entirety of the page; however, it may be confined to any arbitrary region of the page. A Microsoft Silverlight application has the .XAP suffix (XAML Application). The JADE Silverlight thin client is contained in the file JadeAgl.xap. Your HTML files should therefore reference this file. This application acts as the JADE thin client, communicating with the JADE application server and running the user JADE application. The architecture is similar to the traditional thin client, but rather than the normal use of jade.exe as a thin client, JadeAgl.xap runs inside the browser and acts as the thin client. For details about using third-party controls in a Silverlight stateful application, see "Third-Party Control Usage in JADE Silverlight Stateful Applications", in Chapter 4.

Deploying a JADE Silverlight Stateful Thin Client Application The deployment of a JADE Silverlight presentation client application is similar to an application that is based on a system with an application server and classical presentation clients. As in these systems, the Silverlight presentation client is connected to the application server via TCP. This connection is retained until the application terminates.

XamlDevRef - 7.0.10


28

The difference with a Silverlight application is that there is no need for a JADE installation at the presentation client end. The presentation client is the JadeAGL Silverlight application and does not need a JADE system installed to run. The JadeAgl.xap file must be visible to the browser environments. This XAP file must match the version running in the application server. Silverlight as a plug-in handles version changes and ensures that the latest JadeAGL version is present at the browser end. To deploy your XAML application, copy the HTML file and JadeAgl.xap file to the Web server, as well as any image and media files used by the application. Within the Silverlight section of the HTML file is an automatically generated line; for example: You can alter these settings, depending on the location of your application server. These settings are read by JadeAgl.xap when the application starts up and used during initial contact of the JADE application server. Because of a security restriction imposed by Microsoft, whenever a Silverlight user application attempts to open a TCP connection back to the Web server, the system must first confirm that the Web server has given permission for this. The Web server must therefore have a Silverlight Policy Server running that gives the appropriate permissions. The policy server must listen for incoming connections on port 943 and respond to a policy request, by replying with the appropriate XML policy permissions file. JADE provides you with the App=SilverlightPolicyServer, Schema=JadeSchema policy server. This is a nonGUI application that you can run by using a standard JADE shortcut or you can execute it automatically when the application server starts up, by using the JADE initialization file syntax for the initiation of non-GUI applications. (This policy server is used automatically when running a Silverlight application within the JADE development environment.) For details, see "Running a Non-GUI Client Application using jadclient", in Chapter 1 of the JADE Runtime Application Guide, the Application class startApplication, startApplicationWithParameter, or startAppMethod method in Chapter 1 of the JADE Encyclopaedia of Classes, or the ServerApplication parameter in the [JadeServer], [JadeAppServer], or [NonGuiClient] section of the JADE Initialization File Reference. Alternatively, JADE provides example C# source code, derived from a Microsoft example, which you can use to run a simple C# policy server on your Web server. If there is no policy server running on your Web server, the JADE Silverlight presentation client will fail to connect to the application server because Silverlight will deny it access.

Running a JADE Silverlight Stateful Application Running a JADE Silverlight presentation client application is very similar to running an application that is based on a system with an application server and classical presentation clients. Use the Run Application button from the Browser toolbar to run a JADE Silverlight presentation client application. The Run Application dialog is then displayed. For details, see "Running an Application from the JADE Development Environment", in Chapter 1 of the JADE Runtime Application Guide.

XamlDevRef - 7.0.10

Chapter 2

Using the XAML Browser

This chapter covers the following topics. Accessing the XAML Browser Navigating around the XAML Browser Using the XAML Menu Using Function Keys and Shortcut Keys Using Browser Shortcut Keys Adding a New Document Searching for a Document Editing an Existing Document Deleting a Document Renaming a Document Refreshing the View Maintaining Properties for Your Document Saving Your Document Comparing the XAML Changes in Parent and Sub-documents Saving Your Document as another Name Generating XAP and HTML Files Selecting the XAML Browser Mode Hiding or Showing the Toolbar

Accessing the XAML Browser Use the XAML Browser to: Navigate through the XAML documents in your schema View the actual XAML or a preview of the document layout Activate the XAML Painter (for details, see "Accessing the XAML Painter", in Chapter 3) You can start multiple copies of the XAML Browser, which can run in parallel with one or more copies of the XAML Painter.

Note The XAML Browser can be run from a standard or presentation client. However, you cannot toggle to the Paint mode if you are running a standard client.

XamlDevRef - 7.0.10

XAML Developer's Reference Chapter 2 Using the XAML Browser

30

To access the XAML Browser 1.

Select the XAML Browser command from the File menu of a standard browser window. The XAML Browser is then displayed. When you first access the XAML Browser, no document is selected so there is no XAML to display. The name of the schema whose XAML documents you are browsing is displayed in the title bar of the XAML Browser, as shown in the following diagram.

The Navigator pane at the left of the XAML Browser provides a Class Browser that displays only XamlDocument subclasses. The pane at the right of the XAML Browser displays the XAML or a preview of the selected document. 2.

If you want to preview or display the XAML of an existing document in the schema, select the document in the Navigator pane at the left of the XAML Browser. Alternatively, use the Find Document dialog to search for an existing document (for details, see "Searching for a Document", later in this chapter). Click the plus sign (+) at the left of a document in the Navigator pane, to display its sub-documents. To collapse the display of the sub-documents for a document, click on the minus sign (-).

XamlDevRef - 7.0.10


31

XAML for the selected document is displayed, as shown in the following diagram.

The XAML sheet, in the pane at right of the XAML Browser, is displayed by default and displays the XAML of the XamlDocument subclass selected in the Navigator pane.

Note The colors used for elements, attributes, and attribute value on the XAML sheet are JADE default colors and you cannot change them. 3.

To collapse the display of an element, click on a minus sign (-) in the second column. That element, including its closing tag row, is then hidden and a plus sign (+) is displayed in the second column to indicate a hidden element.

4.

Edit the XAML on this sheet, if required. For details, see "Editing an Existing Document", later in this document. We recommend that you use the XAML Painter to add and define the User Interface (UI) elements on your document. For details, see Chapter 3, "Painting XAML Documents".

XamlDevRef - 7.0.10


32

5.

To preview the page of a document subclass, select the Preview tab. The document is then previewed in the pane at the right of the XAML Browser, as shown in the following diagram.

6.

To clear the preview or display of the XAML of the selected document in the schema, click the Clear button in the Navigator pane at the left of the XAML Browser. The document is no longer selected in the Navigator pane and the XAML and Preview sheets are cleared. This does not delete the document.

7.

To close the XAML Browser, click the close icon at the upper-right of the XAML Browser.

For details about accessing the XAML Painter if you are running a presentation client, see "Accessing the XAML Painter", in Chapter 3.

Navigating around the XAML Browser Use XAML Browser toolbar buttons to: Quickly access commonly used functions Switch between the Navigate and Paint modes The toolbar buttons are a point-and-click alternative to other XAML menu actions; for example, the New or Refresh command. For details, see "Using the XAML Menu", in the following section.

XamlDevRef - 7.0.10


33

Note The toolbar is displayed, by default. To hide the toolbar display (for example, if you want to maximize the area for XAML, preview, or painter area), click the close icon at the upper right corner of the toolbar or select the Hide Toolbar command from the XAML menu. To display the toolbar when it has been hidden, select the Show Toolbar command from the XAML menu. The radio buttons on the toolbar enable you to specify the mode in which the XAML Browser operates. Examples of the default Navigate mode are shown in the previous section; that is, "Accessing the XAML Browser". In the Paint mode, the Navigator pane and the pane at the right of the XAML Browser pane are replaced by an instance of the XAML Painter. (In Paint mode, the XAML Browser toolbar is displayed.) For details about the XAML Painter, see "Accessing the XAML Painter", in Chapter 3. For details about selecting the Paint or Navigator mode, see "Selecting the XAML Browser Mode", later in this chapter. Because the XAML Painter is a Silverlight application that can be run only from a presentation client, the Paint mode is disabled when you are not running as a presentation client. When the XAML Browser is active, the XAML menu specific to the XAML Browser is displayed in the JADE development environment, to enable you to change the mode of operation and to recover a hidden toolbar, for example.

Using the XAML Menu The XAML menu enables you to perform XAML functions from within the XAML Browser or XAML Painter. The XAML menu commands are listed in the following table, with their toolbar buttons, where applicable, and a reference to the subsections that provide more details. Button

XamlDevRef - 7.0.10

Command

Description

For details, see…

New

Opens the New XAML Document dialog

Adding a New Document

Edit

Displays the Edit XAML Document dialog

Editing an Existing Document

Delete

Cuts (logically deletes) the document

Deleting a Document

Rename

Renames a document

Renaming a Document

Find Document

Opens the Find Document dialog

Searching for a Document

Refresh

Undoes all changes since the document was last saved and refreshes the view

Refreshing the View

Properties

Accesses the Properties dialog

Maintaining Properties for Your Document

Save

Saves the current document

Saving Your Document

Save As

Saves your document as another name

Saving Your Document as another Name

Generate XAP

Generates the XAP and HTML files of the Silverlight stateless application

Generating the XAP and HTML Files for a Silverlight Stateless Application


Button

34

Command

Description

For details, see…

Mode

Selects the Navigate or Paint mode

Selecting the XAML Browser Mode

Hide|Show Toolbar

Toggles the display of the toolbar

Hiding or Showing the Toolbar

Using Function Keys and Shortcut Keys You can use the keyboard to perform functions to the XAML on the XAML sheet in the pane at the right of the XAML Browser. The keyboard shortcut commands on the XAML sheet follow standard conventions. Press: F1, to display online help for the item with input focus. F4, to display the Find Document dialog.

Using Browser Shortcut Keys Use shortcut keys to quickly perform actions on the XAML sheet of the XAML Browser.

Caret Movement Shortcut Keys The shortcut keys listed in the following table enable you to perform caret movement functions on the XAML sheet by using the keyboard. Key

Moves the caret…

←

One character to the left. When text is selected, moves the caret to the left of the selected text (that is, it falls off the left).

→

One character to the right. When text is selected, moves the caret to the right of the selected text (that is, it falls off the right).

CTRL+←

To the beginning of the word (delimited by white space and an alphanumeric or a non-alphanumeric character) on the left.

CTRL+→

To the beginning of the word (delimited by white space and an alphanumeric or a non-alphanumeric character) on the right.

↑

Up one line.

↓

Down one line.

CTRL+↓

Scrolls down the text displayed on the XAML sheet by one line.

CTRL+↑

Scrolls up the text displayed on the XAML sheet by one line.

CTRL+[

To the top of code on the XAML sheet; that is, to the element.

CTRL+]

To the bottom of the code on the XAML sheet; that is, to the element.

CTRL+/

To the previous word part (press SHIFT to extend the selection).

CTRL+\

To the next word part (press SHIFT to extend the selection).

CTRL+ENTER

To a newly inserted line without performing automatic indenting.

PAGE UP

Up one screen.

PAGE DOWN

Down one screen.

XamlDevRef - 7.0.10


35

Key

Moves the caret…

HOME

To the first non-white space character on the current line if the caret is not already positioned there.

END

To the end of the current line.

ALT +HOME

To the start of the display line (that is, to the first character on the current line).

ALT +END

To the end of the display line.

CTRL+HOME

To the beginning of the text on the XAML sheet.

CTRL+END

To the end of the text on the XAML sheet.

Extending Selected Blocks Shortcut Keys The shortcut keys listed in the following table enable you to extend selected blocks on the XAML sheet. Key Combinations

Action

CTRL+SHIFT +END

Extends selection to end of text on the XAML sheet.

CTRL+SHIFT +HOME

Extends selection to start of text on the XAML sheet.

SHIFT +← or ALT +SHIFT +←

Reduces the selected block one character to the left.

SHIFT +→ or ALT +SHIFT +←

Extends the selected block one character to the right.

SHIFT +END or ALT +SHIFT +END

Extends the selected block to the end of the current line.

SHIFT +HOME or ALT +SHIFT +HOME

Extends the selected block from the caret to start of text within the current line or extends the selection to the start of the line when pressed again (for example, to the start of any whitespace).

SHIFT +↓ or ALT +SHIFT +↓

Extends the selected block to the same column in the next line.

SHIFT +↑ or ALT +SHIFT +↑

Extends the selected block to the same column in the previous line.

SHIFT +PAGE DOWN

Extends the selected block down one screen.

SHIFT +PAGE UP

Extends the selected block up one screen.

SHIFT +CTRL+←

Moves (extends) the selected block left one word of the caret position.

SHIFT +CTRL+→

Moves (extends) the selected block right one word of the caret position.

Insert and Delete Shortcut Keys The shortcut keys listed in the following table enable you to perform insert and delete functions in the XAML sheet by using the keyboard. Key

Action

BACKSPACE

Deletes the character to the left of the caret.

DELETE

Deletes the character to the right of the caret.

CTRL+BACKSPACE

Deletes the word to the left of the caret, and deletes the word to the left of selected text if text is currently selected.

XamlDevRef - 7.0.10


36

Key

Action

CTRL+DELETE

Deletes the word to the right of the caret, and deletes the word to the right of selected text if text is currently selected.

CTRL+INSERT or CTRL+C

Copies the selected portion of the text to the clipboard.

CTRL+SHIFT +BACKSPACE

Deletes to start of line.

CTRL+SHIFT +DELETE

Deletes to end of line.

INSERT

Toggles the insert mode on or off.

SHIFT +DELETEor CTRL+X

Cuts (logically deletes) selected text, and copies it to the clipboard.

SHIFT +INSERT or CTRL+V

Pastes a portion of text from the clipboard to the current position.

Using the Mouse within the XAML Sheet The mouse actions that you can perform in the text area of the XAML sheet are listed in the following table. Mouse Action

Result

Left-click

Moves the caret to the cursor location and cancels the selection.

Double-click

Selects the word at the cursor location.

Triple-click

Selects the line at the cursor location.

Left down and move

Anchors the selection at the down position and extends to follow the cursor location.

SHIFT +left-click

Moves the caret to the cursor location and extends the selection to the new location.

ALT +left down and move

Anchors a rectangular selection at the down position and extends to follow the cursor location.

Using the Mouse within the Line Number Margin The mouse actions that you can perform within the line number margin of the XAML sheet are listed in the following table. Mouse Action

Result

Left-click

Selects the line at the cursor location.

CTRL+left-click

Selects all text in the editor pane.

SHIFT +left-click

Extends the line-based selection from the current anchor point to the line at the cursor location.

Adding a New Document Use a document to create an interface for your JADE XAML applications. A document is a window on which you paint controls (UI elements) for the running of your application. You also use a document to define a print layout. You can create XAML documents (pages) only in the XAML Browser or XAML Painter.

XamlDevRef - 7.0.10


37

A document can be a subclass only of another user-defined document class or of the XamlDocument system class. Existing documents are displayed in the Navigator pane at the left of the XAML Browser, to enable you to select the document that is to be subclassed. A sub-document inherits all of the methods and properties of its parent, or super-document. All documents are subclasses of the XamlDocument class. When you add the first document to your schema, it is automatically created as a subclass of the XamlDocument system class (superclass), inherited from the RootSchema. When you define an application for the schema, specify the XAML document that is to be displayed on start up, in the Startup XAML combo box on the Define Application dialog; that is, the document that is initially created and displayed automatically when the application is started up. For details, see "Specifying a Silverlight Application", in Chapter 1. When you add subsequent documents, they are added as a subclass of the document that is currently selected in the Navigator pane. If you do not want to add a document as a subclass of the currently selected document, click the Clear button to deselect it. The Navigator pane is then cleared of its current selection and the XAML and Preview sheets are also cleared. To add a new document 1.

Perform one of the following actions. Click the New Document toolbar button. Select the New command from the XAML menu. Right-click in the Navigator pane and then select the New command from the popup menu that is displayed. The New XAML Document dialog, shown in the following diagram, is then displayed, to enable you to define your new document.

2.

Specify a document name in the Name text box. You must specify a document name, which cannot have the same name as: Another document in the schema An application name within the current schema Another class in the current schema (or any of its superschemas) Predefined JADE classes or interfaces

XamlDevRef - 7.0.10


38

The document name must start with a letter, and can be a maximum of 30 characters. It can include numbers and underscore characters, but cannot include punctuation or spaces. As documents are defined in the JADE database as classes, the first letter of the name is converted to an uppercase character, if it is lowercase. 3.

If you want the document to be a subclass of another document in the schema, select the superclass in the Subclass of combo box. The document inherits the style of the selected superclass and the Style combo box is then disabled.

4.

If the document is not a subclass of another document, select the appropriate style in the Style combo box. The Subclass of combo box is then disabled. The document style can be one of the following. Grid-based, sizable and scrollable Grid-based, of a fixed size and scrollable Grid-based, of a fixed size Canvas-based, of a fixed size and scrollable Canvas-based, of a fixed size Child window, of a fixed size Popup window of a fixed size

Tip Position your cursor in the Style combo box, to view the default XAML that is associated with the selected style. 5.

Click the OK button. Alternatively, click the Cancel button to abandon your selections.

The XAML Browser then displays the new document in Paint mode. For details, see Chapter 3, "Painting XAML Documents".

Searching for a Document Use the Find Document dialog to search for an existing XAML document and then open it in the XAML Browser. To search for an existing document, perform one of the following actions Select the Find Document command from the XAML menu. Press F4.

XamlDevRef - 7.0.10


39

The Find Document dialog, shown in the following diagram, is then displayed to enable you to specify the name of the document that you want to open.

The Select Required Entry list box displays the XAML documents defined for the currently selected schema. To open an existing document 1.

In the Find text box, enter the name of the document that you want to find. As you enter the name, the document that matches your entry is highlighted in the Select Required Entry list box. Alternatively, if the document is displayed in the Select Required Entry list box, select it.

2.

Click the OK button. Alternatively, click the Cancel button to abandon your selection.

The selected document is then opened in the XAML Browser.

Editing an Existing Document Edit an existing document in the XAML Browser or in the XAML Painter. You can edit an existing XAML document only in the XAML Painter if it is not already open for editing (for example, previewed in the XAML Browser). However, you can edit the XAML of an existing document on the XAML sheet of the XAML Browser in Paint mode, or on the XAML View sheet of the XAML Browser in Paint mode, and then select the Save command in the XAML menu to save your changes. When you edit a document in the XAML sheet, the Edit menu is available so that you can edit the XAML that is currently displayed (for details, see "Using the Edit Menu", in the following subsection).

Note Use the Find Document dialog to search for an existing XAML document and then open it in the XAML Browser. For details, see "Searching for a Document", earlier in this chapter. If you do not save your changes before selecting another document in the Navigator pane, you are prompted to confirm that you want to discard your changes. Click the Yes button to save the current changes and view the selected document, or click the No button to discard the current changes and view the selected document. Alternatively, click the Cancel button, to return to the XAML sheet and save your changes.

XamlDevRef - 7.0.10


40

To edit an existing XAML document, perform one of the following actions Select the Edit command in the XAML menu of the XAML Painter and then use the Edit Xaml Document dialog to specify the document that you want to edit. For details, see "Editing an Existing Document in the XAML Painter", in Chapter 3. Select a XamlDocument subclass in the Class List of the Class Browser and then perform one of the following actions. Select the Edit XAML Document command from the Classes menu. Right-click on the XAML document and then select the Edit XAML Document command from the popup menu that is displayed. Right-click on the Painter toolbar button. This functionality is disabled if the selected class is not a XamlDocument subclass. The XAML Painter displays the document as you edit it. You can select displayed named items and use the mouse to manipulate them. For details, see "Creating a New XAML Document", in Chapter 3.

Using the Edit Menu The Edit menu is displayed in the XAML Browser only in the XAML sheet, to enable you to edit the XAML that is currently displayed. The Edit menu commands, described in the following subsections, are listed in the following table. Command

Shortcut Key

Description

Undo

ALT +BKSP or CTRL+Z

Undoes the last action

Redo

CTRL+Y

Reverses the last action that was undone

Cut

CTRL+X

Cuts a selected portion of text and copies it to the clipboard

Copy

CTRL+C

Copies a selected portion of text to the clipboard

Paste

CTRL+V

Pastes a portion of text from the clipboard to the current caret position

Select All

CTRL+A

Selects all of the text displayed in the XAML sheet

Find/Replace

SHIFT +F3

Locates the specified text in the XAML sheet and optionally replaces that text occurrence

Find Again

F3

Locates the next occurrence of the specified text

Find At Caret

CTRL+F3

Locates the next occurrence of the text on which the caret is positioned

Edit menu commands that are not available for selection are disabled. For example, if you have not selected any text in the XAML sheet, the Cut and Copy commands are disabled, and cannot be selected.

Undo Command Use the Undo command to undo the last action in the XAML sheet, if required, or you can perform multiple undo operations.

XamlDevRef - 7.0.10


41

To undo your last action, perform one of the following actions Select the Undo command from the Edit menu Right-click in the XAML sheet and then select the Undo command from the menu that is displayed Press CTRL+Z Press ALT +BKSP The last action (for example, a keystroke) that you performed in the XAML sheet is then undone. This command is disabled when there is no action that can be undone.

Redo Command Use the Redo command to reverse the last action that was undone. You can repeat the Redo command to step forward and redo actions that were previously undone. To redo the last action undone, perform one of the following actions Select the Redo command from the Edit menu Right-click in the XAML sheet and then select the Redo command from the menu that is displayed Press CTRL+Y Your previously undone action is then redone.

Cut Command Use the Cut command to cut a selected portion of text from the XAML sheet to the clipboard, if required. To cut selected text, perform one of the following actions Select the Cut command from the Edit menu Right-click in the XAML sheet and then select the Cut command from the menu that is displayed Press CTRL+X The selected text is then cut (logically deleted) from the XAML sheet and moved to the clipboard. This command is disabled when there is no text selected in the XAML sheet.

Copy Command Use the Copy command to copy text selected in the XAML sheet to the clipboard, if required. This text can then be pasted at another position in the XAML sheet or in a text editor such as Notepad. To copy selected text to the clipboard, perform one of the following actions Select the Copy command from the Edit menu Right-click in the XAML sheet and then select the Copy command from the menu that is displayed Press CTRL+C The selected text is then copied to the clipboard. This command is disabled when there is no text selected in the XAML sheet.

XamlDevRef - 7.0.10


42

Paste Command Use the Paste command to paste text from the clipboard into the XAML sheet, if required. The pasted text can be a selection that was copied or cut from the XAML sheet. To paste text at the current caret position, perform one of the following actions Select the Paste command from the Edit menu Right-click in the XAML sheet and then select the Paste command from the menu that is displayed Press CTRL+V The selected text is then copied from the clipboard, starting at the current caret position. This command is disabled when there is no text in the clipboard.

Select All Command Use the Select All command to select all of the text that is displayed in the XAML sheet. You can then select the Copy command to copy the selected text to the clipboard. To select all of the text on the XAML sheet, perform one of the following actions Select the Select All command from the Edit menu Right-click in the XAML sheet and then select the Select All command from the menu that is displayed Press CTRL+A All of the text in the XAML sheet is then selected.

Find/Replace Command Use the Find/Replace command to locate text in the XAML sheet and optionally replace the located text with a specified value. To locate and optionally replace text in the XAML sheet 1.

Perform one of the following actions. Select the Find/Replace command from the Edit menu Right-click in the XAML sheet and then select the Find/Replace command from the menu that is displayed Press SHIFT +F3

XamlDevRef - 7.0.10


43

The Find/Replace dialog, shown in the following diagram, is then displayed.

2.

In the Search Text text box, specify the text that you want to locate in the XAML sheet.

3.

In the Replace Text text box, specify the text that is to replace the specified text that is found, if required.

4.

If you want an exact match by case (where uppercase and lowercase is significant), check the Case Sensitive check box. A search is then performed for text with the same capitalization as the text in the Search Text text box. By default, searching is case-insensitive; that is, this check box is unchecked. You can optionally replace text that is located and matched by case with text with the same capitalization as the text specified in the Replace Text text box.

5.

If you want to confirm that each occurrence of the specified search text is replaced with the specified replacement text, check the Prompt on Replace check box. By default, you are not prompted to confirm text replacement; that is, this check box is unchecked. When you select text replacement confirmation and you click the Replace All button, the Verify Replace dialog is displayed every time the search text is located. In the Verify Replace dialog, perform one of the following actions. Click the Yes button to confirm that the located text is to be replaced. Click the No button to leave the highlighted text unchanged and continue searching for the specified text. Click the Cancel button to abandon the search and return focus to the XAML sheet.

6.

If you want to search backwards through the contents of the XAML sheet from the current caret position up to the beginning of the XAML sheet, check the Search Backwards check box. The Search Backwards check box is enabled only when you select the Caret option button in the Start From group box. By default, searching is performed from the current caret position to the end of the XAML sheet; that is, this check box is unchecked. When this option is checked, you have specified your search and replacement text, and you click the Replace All button, the Verify Replace dialog is displayed every time the search text is located.

7.

If you want the search to start from a specific position in the XAML sheet, select the Caret option button in the Start From Group box. The Search Backwards check box is then enabled. By default, the Top option button is selected, indicating that the search begins at the top of the sheet.

8.

To find the next occurrence of the specified text, click the Find button.

XamlDevRef - 7.0.10


44

If JADE finds the text that matches your specified options, the located text is then highlighted and focus is returned to the XAML sheet. If JADE cannot find the text that matches your specified options, a message dialog informs you that the search text was not found and waits for you to click the OK button in the message dialog before returning focus to the XAML sheet. 9.

To replace all occurrences of the specified text in the Search Text text box with the text specified in the Replace Text text box, click the Replace All button. If JADE finds the text that matches your specified options, all occurrences of the located text are then replaced with the specified replacement text and focus is returned to the XAML sheet. If you checked the Prompt on Replace check box, you are prompted to confirm that each occurrence of the located text is to be replaced.

10.

Click the Cancel button to abandon your selection.

Find Again Command When the text specified in the Find/Replace dialog has been located and focus returned to the XAML sheet, you can make further searches for that text. To find the next occurrence of specified text, perform one of the following actions Select the Find Again command from the Edit menu Right-click in the XAML sheet and then select the Find Again command from the menu that is displayed Press F3 The next occurrence of that text is then located and highlighted or the Message dialog is displayed, advising you that the search text was not found if no further occurrences of that text are located.

Find At Caret Command Use the Find At Caret command to locate the next occurrence of the text on which the caret is positioned in the XAML sheet. To locate text on which the caret is positioned, perform one of the following actions Select the Find At Caret command from the Edit menu Right-click in the XAML sheet and then select the Find At Caret command from the menu that is displayed Press CTRL+F3 The next occurrence of that text in the XAML sheet is then highlighted.

Deleting a Document To delete a document 1.

To delete the document selected in the Navigation pane of the XAML Browser or displayed in the XAML Painter, perform one of the following actions. Click the Delete Document toolbar button. Select the Delete command from the XAML menu.

XamlDevRef - 7.0.10


45

Right-click on the document in the Navigator pane and then select the Delete command from the popup menu that is displayed. A message box is then displayed, prompting you to confirm that you want to delete the selected document. 2.

Click the Yes button to delete the document. Alternatively, click the No button to abandon the deletion.

Notes You cannot delete a document if the document has subclasses, any existing property references, or the document is open in the XAML Browser or XAML Painter. When you delete a document, the corresponding class and all its methods are deleted. Any methods referencing the deleted document are flagged as uncompiled.

Renaming a Document You can change the name of an existing document in the current schema. To rename the currently selected document 1.

Perform one of the following actions. Select the Rename command from the XAML menu. Right-click on the document in the Navigator pane and then select the Rename command from the popup menu that is displayed. The Rename of Schema-name::Document-name dialog, shown in the following diagram, is then displayed.

The current name and subclass of the document are displayed in the Name text box and Subclass of combo box, respectively. You cannot update the subclass of the document. 2.

In the Name text box, specify the new name for your document.

3.

Click the OK button. Alternatively, click the Cancel button to abandon the operation.

When a document is renamed, JADE performs the following actions. Updates the associated XAML. Replaces all references with the new name in all entities that referenced the old document name.

XamlDevRef - 7.0.10


46

Note The document name replacement may not be successful in methods that are in error. Recompiles all methods with references to the old document name.

Refreshing the View You can refresh (update) the contents of the XAML Browser or XAML Painter to discard any changes that you have made since the document was last saved. To discard any changes since the document was last saved, perform one of the following actions Click the Refresh – Discard any changes toolbar button. Select the Refresh command from the XAML menu. Right-click on the document in the Navigator pane and then select the Refresh command from the popup menu that is displayed. The browser or painter is then updated and any changes made to the document since you last saved it are discarded. There may be a momentary delay while this updating occurs.

Maintaining Properties for Your Document To maintain the properties associated with your document, use the Properties command from the XAML menu. Alternatively, click the Properties toolbar button. Most of the properties have default settings and many property values are set automatically when you manipulate your document or UI elements in the XAML Painter or you use some of the XAML Painter alignment or layout buttons. In the combo box in the JADE Type column, you can select a subclass of that control, if you have defined any; for example, the combo box for a XAML button control lists any JADE XAML button subclasses that are defined. For details about XAML document and UI element properties, see the JADE Encyclopaedia of XAML Classes. To access the Properties dialog for the document selected in the Navigation pane of the XAML Browser, perform one of the following actions Click the Properties toolbar button. Select the Properties command from the XAML menu. Right-click on the document in the Navigator pane and then select the Properties command from the popup menu that is displayed.

XamlDevRef - 7.0.10


47

The JADE properties for document-name dialog, similar to that shown in the following diagram, is then displayed.

Tip Resize the columns in this dialog, by dragging the vertical grid line to the required position. This may be useful, for example, when viewing property names that can be very long. Click the OK button to save any changes. Alternatively, click the Cancel button to close the JADE properties for document-name dialog.

Saving Your Document To save your document, perform one of the following actions Click the Save Document toolbar button. Select the Save command from the XAML menu. Right-click on the document in the Navigator pane and then select the Save command from the popup menu that is displayed. Press CTRL+S. For details about saving your document as a different name or style, see "Saving Your Document as another Name", in the following section.

XamlDevRef - 7.0.10


48

If you select another document to edit, or attempt to close the XAML Browser before you have saved the changes to the current document, the Query Save Changes dialog, shown in the following diagram, is displayed.

Click one of the following buttons to save or discard your changes. Click the: Yes button, to save the current changes to the document and continue the navigation to the requested action. No button, to discard the current changes to the document and continue the navigation to the requested action. Cancel button, to cancels the navigation and retains all the unsaved changes.

Save Errors When you attempt to save a XAML document JADE validates the XAML. If no errors are found, the document is saved. If JADE finds an error, the appropriate dialog, which contains a description of the error, is displayed. The following subsections describe the save errors that you might encounter (see also, "Comparing the XAML Changes in Parent and Sub-documents", later in this chapter).

XamlDevRef - 7.0.10


49

Invalid XAML If your document contains invalid XAML, the Jade - XAML save error dialog is displayed, which includes the line number and column number of the error in the XAML, as shown in the following diagram.

Click the OK button and then correct the XAML that is in error. The XAML is not saved.

XamlDevRef - 7.0.10


50

Parsing Errors If JADE cannot parse the XAML, an exception is raised and the Exception dialog displays an error number in addition to the line number and column number of the error in the XAML, as shown in the following diagram.

Click the OK button and then correct the XAML that is in error. The XAML is saved. For details about error messages, see the JADE Error Messages and System Messages document.

Single Quotes in the XAML You cannot save your document in the XAML Browser if the XAML contains any single quote characters ('). In the XAML Browser, single quote characters are not allowed and must be replaced with the string ' so that the XAML remains valid. If you attempt to save a document whose XAML contains single quote characters, the dialog shown in the following diagram is displayed.

Click the OK button, replace any single quote characters with ' and then ensure that attribute values are enclosed in double-quote characters. The XAML area of the XAML Painter allows you to use single quote characters as they are converted to the string ' when you save and then view that document in the XAML Browser.

XamlDevRef - 7.0.10


51

Comparing the XAML Changes in Parent and Subdocuments The Compare XAML dialog enables you to compare the XAML of a sub-document with the XAML of the parent document. When you edit a sub-document, you cannot change any of the XAML that was inherited from the parent; that is, the position or property values of those UI elements is fixed. For details, see "Document Subclassing", in Chapter 3. If you make any changes to the XAML of a sub-document that affect the parent document, the dialog shown in the following diagram is displayed when you try to save your changes.

Click the No button, to return to the XAML Browser or the XAML Painter. Alternatively, click the Yes button, to compare the changed XAML in the sub-document with that of the parent document. The Compare XAML dialog, shown in the following diagram, is then displayed.

XamlDevRef - 7.0.10


52

The Latest pane (at the left) displays the XAML of the sub-document. The Original pane (at the right) displays the XAML of the parent document (from which the sub-document is derived). In the Latest and Original panes, the corresponding lines of XAML that have invalid changes are highlighted with a green background. As these panes are read-only, you cannot change the XAML in either of them. Use the XAML Browser or the XAML Painter, to change the XAML (for details, see "Editing an Existing Document", earlier in this chapter). Click the Next button to view the next line of the XAML that has been updated and the parent document, if applicable, or the Previous button to highlight the previous line of XAML that has been updated and the parent document. Click the Cancel button, to close the Compare XAML dialog and return to the XAML Browser or XAML Painter.

Saving Your Document as another Name Use the Save As command from the XAML menu to save your document as a new document with a different name. Alternatively, if you have started painting a XAML document but have not yet added it, use this command to save your document. To save the currently selected document as a new document 1.

Perform one of the following actions. Select the Save As command from the XAML menu. Right-click on the document in the Navigator pane and then select the Save As command from the popup menu that is displayed. The Save Document-name as dialog, shown in the following diagram, is then displayed.

2.

In the Name text box, specify the name under which to save the copy of the document. The specified name must be unique in the current schema. As you cannot save your document under a different superclass or schema, the Subclass of combo box is disabled on this dialog.

3.

Click the OK button. Alternatively, click the Cancel button to abandon the operation.

XamlDevRef - 7.0.10


53

Generating XAP and HTML Files Use the Generate XAP command to generate the XAP and HTML files for your Silverlight stateless application. For details about generating the XAP and HTML files by using the jadclient command line, see "Generating the XAP and HTML Files for a Silverlight Stateless Application", in Chapter 1. See also, "Requirements to Generate XAP and HTML Files", in Chapter 1. To generate the XAP and HTML files of your Silverlight stateless application 1.

Select the Silverlight stateless application for which you want to generate XAP and HTML files.

2.

Select the Generate XAP command from the XAML menu of the XAML Browser. This command is disabled if the selected application is not a Silverlight stateless application type. The XAP File Generator dialog, shown in the following diagram, is then displayed.

3.

In the Application combo box, select the application. By default, the Silverlight stateless application is selected.

4.

In the XAP File Name text box, specify the name of the XAP file that is to be generated. By default, the XAP file name is the same as the application name.

5.

In the Launching HTML File Name text box, specify the name of the HTML file that is to be generated. By default, the HTML file name is the same as the application name.

6.

In the Result Directory text box, specify the directory where the XAP and HTML files are placed at the end of a successful build. Specify a directory or path relative to the machine on which you are generating the files. For details, see "Generating the XAP and HTML Files for a Silverlight Stateless Application", in Chapter 1. Use the Browse button to search for the output directory, if required. When you click the Browse button, the common Browse for Directory dialog is then displayed, to enable you to select the appropriate location.

7.

To retain the build directory, check the Retain XAP build directory check box. When this check box is checked, if the build fails, the log files are not copied to the logs directory, as these files can be found in the retained build directory.

XamlDevRef - 7.0.10


8.

54

Click the Generate button to generate the files. Alternatively, click the Cancel button to abandon your entries.

While the files are the being generated, the XAP File Generation Progress dialog is displayed, checking off actions as they are successfully completed, as shown in the following diagram.

For details about the generation process and how JADE records any failures, see "Generating the XAP and HTML Files for a Silverlight Stateless Application", in Chapter 1.

Selecting the XAML Browser Mode The XAML Browser enables you to select the operating mode. By default, the XAML Browser is displayed in Navigate mode, which enables you to navigate around your XamlDocument subclasses. In Paint mode, the navigator region and the XAML or preview region is replaced by an instance of the XAML Painter.

Note You cannot use the XAML Browser in Paint mode if you have unsaved XAML code changes. You can, instead, use the Preview sheet to preview the effect of your changes to the XAML code that you made on the XAML sheet. To toggle the mode of operation, perform one of the following actions Click the required Paint or Navigate radio button in the toolbar. Select the Mode command from the XAML menu and then select the required Paint or Navigate mode. The selected mode is then displayed, and a check mark symbol (✓) is displayed to the left of the command in the Mode submenu.

Note The Paint option is disabled if you are not running JADE on a presentation client (that is, you are running a standard client or you attempted to operate in Paint mode on an application server), because the XAML Painter is a Silverlight application that can run only from a presentation client.

Hiding or Showing the Toolbar The toolbar is displayed by default in the XAML Browser (in the Navigate and Paint modes). You can hide the toolbar if you want to maximize the area for XAML or the preview area, for example.

XamlDevRef - 7.0.10


To toggle the display of the toolbar Select the Hide Toolbar or Show Toolbar command from the XAML menu. When the toolbar is displayed, click the close icon at the upper right of the toolbar. When the toolbar has been hidden, the Show Toolbar command is displayed in the XAML menu instead of the Hide Toolbar command. To display the toolbar when it has been hidden, select the Show Toolbar command from the XAML menu.

XamlDevRef - 7.0.10

55

Chapter 3

Painting XAML Documents

This chapter covers the following topics. Using the XAML Painter Accessing the XAML Painter Properties Area of the XAML Painter Painting Area of the XAML Painter XAML Area of the XAML Painter Using Function Keys and Shortcut Keys Creating a XAML Document Adding a New XAML Document Adding UI Elements to Your Document Defining the Layout of Your XAML Document Maintaining Properties for Your XAML Document or UI Element Defining Methods for Your Document Saving Your Document Editing an Existing Document in the XAML Painter Using the Keyboard and Mouse to Edit Your Document Changing a UI Element Type Effects of Editing an Existing Document Deleting a Document Layout Toolbar

Using the XAML Painter Use the XAML Painter to: Paint User Interface (UI) elements onto XAML documents in your schema View and maintain the XAML of a XAML document The XAML Painter enables you to create and maintain XAML documents of your Silverlight application. The XAML Painter is a graphical user interface (GUI) painter that supports bitmaps, list boxes, button controls, and so on. XAML documents have references to UI elements, which have properties, events, and event logic defined on them. UI elements display information and permit user input. The properties of UI elements determine aspects of their appearance (for example, position, size, or color) and aspects of their behavior (for example, whether they can be resized).

XamlDevRef - 7.0.10

XAML Developer's Reference Chapter 3 Painting XAML Documents

57

Note You cannot paint a XAML document until you have created that document. For details, see "Adding a New XAML Document", later in this chapter. Alternatively, if you have started painting a XAML document but have not yet created it, use the Save As command to save your document. For details, see "Saving Your Document as another Name", in Chapter 2. The XAML Painter provides for "what you see is what you get" (WYSIWYG) painting of XAML documents in a similar manner to the JADE Painter. Additionally, it enables you to view and update the XAML contained within the XAML document. You can start multiple copies of the XAML Painter, which can run in parallel with one or more copies of the XAML Browser. (For details about the XAML Browser, see Chapter 2.)

Notes The XAML Painter can be run only from a presentation client and if a base locale is set for your JADE system. In addition, you cannot toggle to the Paint mode to preview a document in the XAML Browser if you are running a standard client. You can access the XAML Painter from a user-defined schema only; that is, you cannot access it from the RootSchema.

Accessing the XAML Painter To access the XAML Painter, perform one of the following actions Select the XAML Painter command from the File menu of a standard browser window. When a XamlDocument subclass is selected in the standard JADE development environment Class Browser, perform one of the following actions. Select the Edit XAML Document command from the Classes menu. Right-click on the XAML document in the Class List pane and then select the Edit XAML Document command popup menu that is then displayed. Right-click on the Painter toolbar button (you must have already selected a XAML document in the Class List pane).

XamlDevRef - 7.0.10


58

The XAML Painter is then displayed. If you accessed the XAML Painter from the Class Browser, the XAML for the selected document subclass is then displayed, as shown in the following diagram.

You can also access the XAML Painter by using the XAML Browser in Paint mode. For details, see "Selecting the XAML Browser Mode", in Chapter 2. The XAML Painter contains the following areas. Properties area, at the left of the painter, lists the dialogs that enable you to set the properties of the UI elements of the document that you are editing. The Controls dialog is the only dialog that is expanded when you first open the XAML Painter. For details, see "Properties Area of the XAML Painter", later in this chapter. Painting area at the upper-right of the painter shows the document as you are editing it. In addition, that Painting area has a toolbar and additional options to help you to layout the UI elements on your document. The additional options, displayed when you click the options hyperlink, are not displayed by default. For details, see "Painting Area of the XAML Painter", later in this chapter. XAML area, at the lower-right of the painter, displays the XAML code of the document that you are editing or additional instructions about the XAML Painter. For details, see "XAML Area of the XAML Painter", later in this chapter. For details about the XAML menu of the XAML Painter, see "Using the XAML Menu", in Chapter 2.

XamlDevRef - 7.0.10


59

Properties Area of the XAML Painter The left side of the XAML Painter contains dialogs that enable you to specify properties on the current document and its UI elements, as well as additional views that allow for a variety of ways for interacting with the current document. When you change a property by using a dialog in the Properties area, the associated XAML attribute is updated and the Painting area and XAML area are updated immediately. You can also change the properties of a UI element or document by editing the code on the XAML View sheet directly (you must click the Load XAML button, to see your changes) in the Painting area. An example of the Properties area, with the Controls dialog fully expanded, is shown in the following diagram.

Expand or contract each dialog individually by clicking on the arrow at the upper left of that dialog. (When you position your cursor over the button, the arrow turns light-blue.) If more properties are available to view in that dialog, More… is displayed at the lower left of that dialog. Click the adjacent arrow to additionally expand that dialog.

XamlDevRef - 7.0.10


60

Alternatively, to expand or contract all of the dialogs in the Properties area, click the toggle expanders hyperlink at the upper right of the Properties area. Depending on the document type or UI element that you are maintaining, some or all of the following dialogs may be displayed in the Properties area. Controls dialog provides access to the UI elements that you can add to the current document. Add UI elements by using the Available Controls combo box, in which UI elements are sorted alphabetically, or by using the Controls by Category tree view, which groups UI elements by type. For details about adding a UI element to a document, see "Adding UI Elements to Your Document", later in this chapter. Use the Page Controls combo box to search for a UI element on a document. For details, see "Selecting a UI Element", later in this chapter. Zoom dialog enables you to zoom in and out of the current document, which is useful to see the complete document or to concentrate on a specific part of a document. For details, see "Expanding or Contracting the View of a Document", later in this chapter. Document Outline dialog, shown in the following diagram, provides a hierarchy view of the current document.

The Page element is the highest level in the document hierarchy. The number of sub-elements depends on the document that you are viewing. Click the unfilled arrow at the left of an element to expand it and display its sub-elements. An element that is fully expanded displays a dark solid arrow at its left. An element that has no sub-elements displays no arrow. Select an item in this dialog to select the corresponding UI element in the Painting area or to edit its properties using the available dialogs in the Properties area. The selected UI element is then highlighted with a red border in the Painting area. Select multiple UI elements by holding down CTRL and then clicking on each element in the Document Outline dialog (or the Painting area). The master UI element is displayed with a red border and subsequent selections have a green border. Changes that you make are applied to all of the selected UI elements. For details about selecting one or more UI elements, see "Selecting a UI Element", later in this chapter. General Properties, Size and Position, Colors and Styling, Fonts, Grid Definition, Miscellaneous, and Transformations dialogs enable you to maintain properties that are specific to the selected UI element. For details, see "Maintaining Properties for Your XAML Document or UI Element", later in this chapter.

XamlDevRef - 7.0.10


61

Expanding or Contracting the View of a Document The Zoom dialog is useful when you require a: Close view of a section of a document; for example, if you need to concentrate on a specific part of a document. Complete view of a document; for example, so that you can see the layout of the UI elements on a document. The zoom ranges in magnification from 10 percent through 800 percent of the document size and does not affect the saved size of the document. Click the Reset button, to reset the zoom to 100 percent. To expand or contract the view of a document Click the expander button at the upper-left of the Zoom dialog, in the Properties area, to display the Zoom dialog shown in the following diagram.

The area that is currently visible in the Painter area, at the right of the XAML Painter, is represented by a light-purple shaded area, referred to as the zoom navigator overlay in this section. If the whole document is visible in the Painter area, the zoom navigator overlay is not displayed. To zoom in on the document, perform one of the following actions Slide the Zoom slider to the right. In the text box at the right of the Zoom slider, enter the magnification at which you want to view the document in the text box and then press ENTER. The document in the Painter area is then enlarged; that is, zoomed in. You could have to scroll horizontally or vertically to view other parts of the document in the Painter area. Alternatively, use the Zoom navigator overlay to move around in the Painter area. Scrolling the Painter area updates the current view in the zoom preview window. The zoom preview window is a live copy of the UI elements on the document that you are editing. If you are viewing a complex document, it may be advisable not to show the preview in the zoom window. The zoom and navigation behavior is still available.

XamlDevRef - 7.0.10


62

To zoom out from the document, perform one of the following actions Slide the Zoom slider to the left. In the text box at the right of the Zoom slider, enter the magnification at which you want to view the document in the text box and then press ENTER. The document in the Painter area is then reduced; that is, zoomed out.

Painting Area of the XAML Painter The Painting area shows the layout of the UI elements on the document that you are editing. Use the Painting area and the dialogs in the Properties area to manipulate the size, position, and alignment of UI elements on the document. You can select and manipulate items in the Painting area using the mouse. The Properties area at the left of the XAML Painter displays the properties of the selected item (or the primary selection in a multiple-selection situation). The Options panel, shown in the following diagram, is at the top of the Painting area and contains a set of tools that are frequently used when manipulating the layout of UI elements on your document.

The additional alignment check boxes, displayed when you click the options hyperlink, are not displayed by default. The following table lists the hyperlinks at the left of the Options panel. Hyperlink

Description

delete

Deletes the selected UI element or elements.

undo

Undoes the last action that you performed. You can undo up to ten previous actions.

redo

Redoes the last action that you performed. You can redo up to ten actions.

xaml

Toggles (displays or hides) the XAML area.

The Layout toolbar buttons enable you to align selected UI elements on a document. For details, see "Layout Toolbar", later in this chapter. Alignment check boxes, displayed at the bottom of the Options panel when the options hyperlink is clicked at the right of the toolbar, are enabled only for UI elements that have a Canvas parent. For details, see "Options Panel Check Boxes", later in this chapter. For details about using the Layout toolbar buttons and additional layout options, see "Defining the Layout of Your XAML Document", later in this chapter.

XAML Area of the XAML Painter The XAML area, at the lower-right of the XAML Painter, contains the following sheets. XAML View sheet, which displays the XAML code of the document that you are editing. Edit the XAML code on this sheet manually, if required. If you edit XAML code by using the XAML View sheet, click the Load XAML button to update your view of the Painting area.

XamlDevRef - 7.0.10


63

The code in the XAML View sheet is updated immediately, if you edit a UI element by using a properties dialog, or by directly interacting with the UI element in the Painting area.

Note If you edit the XAML document manually, ensure that you are making valid changes; for example, do not have duplicate names, do not duplicate any x:Uid attributes, and so on. If you attempt to load invalid XAML, the XAML Painter may not be able to catch any exceptions raised by the Silverlight plug-in. In the worst case, Silverlight does not raise an exception that the XAML Painter can catch, it simply crashes and you must restart the XAML Painter. The XAML that is displayed on the XAML View sheet is sent back to JADE when you save the document. That XAML is then parsed and used to build the JADE representation of the document. General Instructions sheet, which displays an overview about how to use the Painter area to manipulate the UI elements of a document. The details on this sheet are read-only. Hide the XAML area, if you want to maximize the Painting area for the document that you are editing. To toggle the display of the XAML area Click the xaml hyperlink, in the Options panel. To select all of the XAML code that is displayed on the XAML View sheet Click the Select All button. You can then copy the XAML into a new document by using standard cut and paste functionality.

Using Function Keys and Shortcut Keys You can use the keyboard to perform functions to the XAML on the XAML View sheet of the XAML Painter. The keyboard shortcut commands on the XAML View sheet follow standard conventions. In addition, the XAML View sheet uses some, but not all, of the keyboard shortcuts that the XAML Browser uses. For details, see "Using Browser Shortcut Keys", in Chapter 2. Press F1 to display online help for the item with input focus. The following table summarizes the most common keyboard and mouse interactions used to perform various actions in the Painting area. Key or Combination

Description

CTRL+left-click

Selects additional UI elements (this also applies in the Document Outline dialog).

ALT +left-click

Clones the currently selected UI element (and its sub-elements), to build multiple controls. This enables you to build an interface quickly. For example, to copy a StackPanel that contains a TextBlock and a ComboBox: 1.

Select the StackPanel.

2.

Press ALT .

3.

Drag the StackPanel to the new position on the document.

After you release the mouse button, the StackPanel and its child UI elements are copied to the new position on the document. SHIFT +left-click

XamlDevRef - 7.0.10

Attempts to re-parent the dragged UI element onto the item under the cursor.


Key or Combination

Description

ALT +SHIFT +left-click

Clones the selected UI element and moves the clone onto the target parent.

ESC

Deselects all currently selected UI elements.

DELETE

Deletes the currently selected UI elements.

Creating a XAML Document This subsection covers the following topics. Adding a New XAML Document Subclassing XAML Controls and Documents Adding UI Elements to Your Document Selecting a UI Element Cloning UI Elements Naming a UI Element Adding Container UI Elements Changing the Caption Content of a UI Element Overlapping UI Elements Changing the Runtime Tab Sequence Obtaining Help for a UI Element Defining the Layout of Your XAML Document Sizing Your UI Elements Aligning Your UI Elements Spacing Your UI Elements Options Panel Check Boxes Using Grid Lines to Position UI Elements on XAML Documents Locking the Position of UI Elements on Your Document Direct Select Functionality Previewing UI Elements on Your Document Examples of Laying Out UI Elements Maintaining Properties for Your XAML Document or UI Element Maintaining General Properties Maintaining Size and Position Properties Maintaining Colors and Styling Properties

XamlDevRef - 7.0.10

64


65

Maintaining Font Properties Maintaining Grid Definitions Maintaining Miscellaneous Properties Maintaining Transformations Defining Methods for Your Document

Adding a New XAML Document Use a XAML document to create an interface for your JADE applications. A XAML document is a window on which you paint UI elements for the running of your application. UI elements are objects such as text boxes, list boxes, buttons, check boxes, and so on. You can create documents in the XAML Browser or the XAML Painter. If you create a document from the XAML Browser when in Navigate mode, the XAML Browser changes to Paint mode automatically after you click the OK button on the New XAML Document dialog. All XAML documents are subclasses of the XamlDocument class. A document can be a subclass only of another user-defined document class or of the XamlDocument system class. Existing documents are listed in the Subclass of combo box, to enable you to select the document that is to be subclassed. A sub-document inherits all of the methods and properties of its parent, or super-document. For details, see "Subclassing XAML Controls and Documents", in the following subsection. The XAML UI element hierarchy is located under the XamlObject class. Create a new XAML document by: Creating a new top-level document Subclassing an existing document If you create a top-level document, you can apply an initial structural template to the document (by using the Style combo box on the New XAML Document dialog). The structural template provides an initial framework on which you can build your document.

Note When you define an application for your schema, you must specify the XAML document that is displayed when the application is started. For details, see "Defining a Silverlight Application", in Chapter 1. To create a new XAML document 1.

Select the New command from the XAML menu. The New XAML Document dialog is then displayed. For details, see "Adding a New Document", in Chapter 2.

2.

After you click the OK button, the new document is opened in the XAML Painter, ready to be edited. Depending on the type of document that you created, some basic XAML code is displayed in the XAML View sheet, by default.

3.

After you make your changes, press CTRL+S or select the Save command from the XAML menu, to save your document.

The document is not saved automatically and displays unsaved in the title until you save it.

XamlDevRef - 7.0.10


66

If you attempt to select another document or to close the XAML Painter before you have saved the changes to the current document, the Query Save Changes dialog is displayed. For details, see "Saving Your Document", in Chapter 2. An example of a new unsaved document in the Grid Based - Sizeable, Scrollable style is shown in the following diagram.

Note If you create the document in the XAML Painter, the Navigator pane at the left of the XAML Browser is updated immediately after you save the document. After you create a XAML document, you can paint UI elements onto the document, by using the Painting area or by editing the XAML on the XAML View sheet. For details, see "Adding UI Elements to Your Document", later in this chapter. After adding UI elements, you can additionally manipulate them by using your mouse to select or move them. The properties of the selected UI element are displayed in the Properties area. Named UI elements only can be selected in the Painting area or the Properties area. All UI elements added in the XAML Painter are named, by default. A named UI element has a Name XAML attribute. An unnamed UI element cannot be considered a potential parent UI element. Name a UI element manually, if required. For details, see "Naming a UI Element", later in this chapter. All named UI elements are available as references in JADE when you save the document.

XamlDevRef - 7.0.10


67

If you want a UI element to be selectable in the XAML Painter but you do not want it to be a referenced item in JADE, clear the name of the UI element in the Name text box in the General Properties dialog. The UI element is then assigned a painter-only name that allows for interaction in the XAML Painter; for example, _NoJadeName_1. The base element of the document (typically the background or LayoutRoot element) can be selected, but does not allow itself to be moved by dragging. The reason for this is that the layout style usually determines the position of the element in the browser at run time and you must, therefore, make an explicit decision to set up offset margins and so on for your document; otherwise, it is easy to drag the element around, creating offsets, without visualizing what would happen to the position at run time. To move or resize the base element, use the Size and Position dialog in the Properties area. For details, see "Maintaining Colors and Styling Properties", later in this chapter.

Tip When subclassing a document, introducing a panel or panels that will contain all of the new sub-document UI elements reduces the number of placeholder items that need to be reflected throughout the XAML hierarchy. To find a UI element on your document, select that UI element in the Page Controls combo box in the Controls dialog and then click the Find button, or select that UI element in the Document Outline dialog. The selected element is then highlighted with a red border in the Painting area. For details, see "Selecting a UI Element", later in this chapter.

Subclassing XAML Controls and Documents Although you can apply JADE-style subclassing to XAML controls (subclasses of UIElement) and XAML documents (subclasses of XamlDocument), there are several things of which you should be aware. For details, see the following subsections.

Control Subclassing All of the classes in the JADE hierarchy under UIElement represent controls that can be subclassed. Subclassed controls are listed in the Available Controls combo box in the Properties area of the XAML Painter. In the XAML code, the type of the control is always the type that JADE uses for the superclass. For example, if you subclass XamlButton as MyXamlButton, in the XAML Painter you can add a MyXamlButton to the document. The JADE reference created for this UI element is of the type MyXamlButton, but in the XAML code it is a Button. (The JADE class XamlButton maps to the Button XAML object.) Control subclassing should be used only to specify special functional behavior and it should not be used to redefine the look and feel of a control. To change the look and feel of a control, you must add a resource, written in XAML, to the document and then apply this resource to the control using the style or template property of the control. Function and look and feel are completely separated in the Silverlight environment and subclassing should be used only to define different functionality.

Document Subclassing When you create a new XamlDocument, you can specify the document of which it will be a sub-document (or subclass). The points to note about subclassed documents are as follows. A sub-document includes all of the XAML of the document from which it was created; that is, the parent or super-document. The sub-document, therefore, initially looks the same as the parent document and contains the same UI elements. When you edit a sub-document, you cannot change any of the XAML that was inherited from the parent; that

XamlDevRef - 7.0.10


68

is, the position or property values of those UI elements is fixed. You can, however, add new UI elements to the sub-document. New UI elements must be named and you can add additional content (which does not need to be named) to new UI elements. If you add content to a document that has sub-documents, those sub-documents are also updated with the new content. A UIElement (a control) has a property created in the corresponding JADE class for the top-most level in which that control is defined; for example, top-level document D1 has a button b1, and sub-document D2 has button b2. In the class D1 in JADE will be a property b1, and class D2 (a subclass of D1) will have a property b2. However, the XAML for D2 will, by the above rules, contain a UIElement for b1. JADE connects XAML UIElements to JADE properties by inserting a Unique Identifier (Uid) attribute into the XAML. JADE adds placeholders, with an appropriate Uid value, in the XAML of the parent document at the place where you add the new UI element in the sub-document. This is required so that changes to the parent document can be populated to the XAML of the sub-document.

Caution If directly editing the XAML, take great care if you alter the Uid attribute. The Uid attribute in the XAML is updated only after you save your changes. The Compare XAML dialog enables you to compare the XAML of a sub-document with the XAML of the parent document. For details, see "Comparing the XAML Changes in Parent and Sub-documents", in Chapter 2.

Adding UI Elements to Your Document Use the Controls dialog in the Properties area to add a new UI element to your current document. In addition to adding UI elements from the Controls dialog, you can clone the currently selected UI element (and its sub-elements), to quickly build multiple controls. For details, see "Cloning UI Elements", later in this chapter.

Note You can also add a UI element by editing the XAML directly in the XAML View sheet. If you copy and paste UI elements within the XAML View sheet, ensure that Name attributes are unique. For details about editing a document, see "Editing an Existing Document", later in this chapter. All actions occur against the currently selected UI element or elements. To clear all selections in the Painting area, press the ESC key.

Note You cannot paint a XAML document until you have created that document. For details, see "Adding a New XAML Document", earlier in this chapter. Alternatively, if you have started painting a XAML document but have not yet created it, use the Save As command to save your document. For details, see "Saving Your Document as another Name", in Chapter 2. To add a new UI element to your document 1.

Select the level at which to add the UI element within the document; for example, if you select an existing UI element, the one you are adding is added as a child. Use the Document Outline dialog, to select the level at which you want to add the UI element. Alternatively, select the required UI element, in the Painting area.

XamlDevRef - 7.0.10


2.

69

To specify the type of UI element that you want to add, perform the following actions in the Controls dialog. a.

In the Available Controls combo box, select the type of UI element that you want to add. Alternatively, click the More button to expand the Controls dialog and then select the required UI element under the Controls by Category tree.

b.

Click the Add button.

The specified UI element is then displayed at the upper left of the document in the Painting area and the corresponding XAML code is added to the XAML area.

Note A Silverlight popup-type control cannot be directly displayed in the XAML Painter because it does not have a development-mode operation. The XAML Painter substitutes a XamlBorder control for the popup window when displaying the control, provided that the XamlPopup window is the direct content of a top-level element. If it is not, neither the popup window nor its content can be displayed or selected. When a XamlPopup control can be displayed using a XamlBorder control substitute, the painter operation is seamless, except that only changes to the Width and Height properties for the popup window are displayed in the Painting area. You can view other property changes to that control only at run time. 3.

Select the UI element and then size and position it accordingly. To: Size the UI element, drag the border of the UI element to the required size. When you position your cursor over a border, it becomes a double-headed arrow indicating that you have selected a border. Position the UI element, click inside the UI element, and then drag it to the required position on your document. For details, see "Defining the Layout of Your XAML Document", later in this chapter.

4.

Apply properties to your UI element by using the dialogs in the Properties area. For details, see "Maintaining Properties for Your XAML Document or UI Element", later in this chapter.

5.

To save your document, select the Save command from the XAML menu, or press CTRL+S.

All UI elements are children of the document or container UI element on which they are painted. Being a child UI element affects the placement of the UI element within the parent document or container. The left and top properties of a UI element are relative to the parent UI element. Moving the document or container also moves the UI elements.

Tip Check the Grid Lines check box, in the Options panel, to display grid lines to assist you to position your UI elements on the document, if required. (For details, see "Defining the Layout of Your XAML Document", later in this chapter.) For details about changing the type of an existing UI element on a document (for example, changing a ComboBox UI element to a TextBox UI element), see "Changing a UI Element Type" under "Editing an Existing Document in the XAML Painter", later in this chapter.

Selecting a UI Element Select a UI element to move or resize it on your document or to change its properties.

XamlDevRef - 7.0.10


70

Note You can select only named UI elements in the Painting area or the Properties area. All UI elements added in the XAML Painter are named, by default. Name a UI element manually, if required. For details, see "Naming a UI Element", later in this chapter. To select a UI element Perform one of the following actions. In the: Painting area, select the UI element. To select disabled UI elements (that is, elements that you cannot select by using your mouse), use the Page Controls combo box or select it on the XAML View sheet. Controls dialog, select the UI element in the Page Controls combo box and then click the Find button.

Note You can select the XamlMediaElement, XamlItemsControl, XamlContentControl, XamlImage UI elements using the Page Controls combo box only; that is, you cannot select them by using your mouse. After the XamlImage and XamlMediaElement elements have content, you can select them in the Painting area by using your mouse. Document Outline dialog, select the UI element.

Note You could have to scroll around the Painting area until you can see the selected UI element. The selected UI element is then highlighted by a red border if it is the first (that is, master selection) UI element selected in a series. Properties of that UI element are then displayed in the dialogs in the Properties area. UI elements selected in addition to the master element are highlighted with a green border. The master selection can be moved by clicking somewhere inside the red border and dragging it to the required position. If you selected multiple UI elements, they are moved relative to the master selection. Similarly, if you resize the master selection, all other selected UI elements are resized accordingly. To select additional UI elements, press CTRL and then select each UI element. Subsequent UI elements are highlighted with a green border. If you move or resize the master UI element, all other selected UI elements are move or resized accordingly. In the following diagram, All items is the master selection and Retail items and Items for tender are additional selections.

To deselect a UI element that is already selected While holding down the CTRL key, click on the UI element that you do not require in the selection.

Cloning UI Elements Clone the currently selected UI element (and its sub-elements), to quickly build multiple controls.

XamlDevRef - 7.0.10


71

To clone one or more UI elements 1.

Select the UI element or container that you want to clone. For details, see "Selecting a UI Element", earlier in this chapter.

2.

Press ALT +left-click. For details, see "Using Function Keys and Shortcut Keys", earlier in this chapter.

The cloned UI elements are then displayed at the top left of your document.

Naming a UI Element Any UI element added directly in the XAML Painter is named. However, if you introduce code from an external tool, the provided control elements may not be named. To name a UI element manually 1.

Edit the XAML on the XAML View sheet, to add a Name attribute to the UI element. If you add a Name attribute, you must follow the attribute naming convention that is used in the rest of the document; for example, the document could use the convention Name="MyControl" or x:Name="MyControl", or some variation. You cannot use different attribute naming conventions in the same document.

2. Click the Load XAML button, to load your changes into the current editing session. Named UI elements display their name in square brackets in the hierarchy in the Document Outline dialog; for example, the named Button item in the following diagram displays [btnErrorOk].

Adding Container UI Elements JADE XAML enables you to add multiple UI elements to other UI elements. This document refers to any UI element that contains other elements as a container. The following are the main styles of UI element that you use in JADE XAML. A ContentControl allows only a single piece of content; for example, a caption on a button. An ItemsControl can display a collection of items; for example, a ListBox or a ComboBox. The Panel is a layout manager type of control. The Canvas, Grid, and StackPanel UI elements are types of Panel. Panels are designed to hold multiple UI elements. The layout of UI elements within the Panel

XamlDevRef - 7.0.10


72

depends on the type Panel (as each panel type exerts its own layout requirements on the UI elements it contains). For details, see "Using Layout Manager UI Element Types", in Chapter 4. Even though a ContentControl is allowed only one piece of content, there is no restriction on the type of content (as long as there is only one). In the XAML Painter, if you drag a UI element into a ContentControl that already has content, the painter recognizes the existing content and: 1.

Removes the existing content from the UI element.

2.

Adds a StackPanel in the place of the original content (respecting the rule that a ContentControl can have only one child item).

3.

Adds the original content to the StackPanel as well as the UI element that you were trying to add.

The ContentControl has one piece of content; that is, the StackPanel. The StackPanel can contain multiple UI elements, and it now manages the content that you want to display. A container UI element must be added before the UI elements that it is to contain. When a container UI element is in place, other UI elements can be added within its boundaries. The following diagram shows an example of Button, CheckBox, and ListBox UI elements within a Canvas container.

To move an existing UI element in a container, use the mouse to drag the UI element to the required position.

Changing the Caption Content of a UI Element The Content property or attribute of a UI element determines the caption that is displayed on that element at run time; for example, a button name. To change the content of a UI element 1.

Select the UI element whose content you want to specify. For details, see "Selecting a UI Element", earlier in this chapter.

2.

Perform one of the following actions. In the: General Properties dialog, enter the content in the Content text box and then press the ENTER key or the TAB key.

XamlDevRef - 7.0.10


73

Painting area, perform a long-left-click on the UI element. The UI element is then highlighted in orange and the content text is selected for editing, as shown in the following diagram.

Edit the content, as required, and then click outside the element, to view your change. XAML View sheet, edit the Content attribute of the UI element and then click the Load XAML button. The content is then updated.

Overlapping UI Elements When two or more UI elements overlap, you can specify which UI element appears on top of or behind the other UI element or elements, by using the XAML View sheet. The UI elements on a Canvas have an additional property, the zIndex, that enables you to specify which UI element sits on top of another. For details, see "Canvas UI Element Type", in Chapter 4. UI elements are added to a document or container in controlList order (that is, the order in which you add them to the document or container). The last UI element in the controlList order is displayed on top of any other UI elements in the document or container, by default. In the following example, the ListBox UI element is the last in the controlList and is displayed on top of the CheckBox UI element in the container (all UI elements in the examples have the same zIndex value).

In the following example, the CheckBox UI element is the last in the controlList and is displayed on top of the ListBox UI element in the container.

XamlDevRef - 7.0.10


74

Changing the Runtime Tab Sequence The TabIndex property or attribute of a UI element determines its tab sequence order on a document at run time. Specify the tab order of each UI element on a document individually. To change the tab sequence that the user experiences at run time 1.

Select the UI element whose tab sequence order you want to specify. For details, see "Selecting a UI Element", earlier in this chapter.

2.

In the General Properties dialog, enter the tab sequence order value in the TabIndex text box. Enter a value in the range 1 through 9999. Alternatively, edit the TabIndex attribute of the UI element on the XAML View sheet.

3.

Press the ENTER key or the TAB key, or click the Load XAML button if you edited the value on the XAML View sheet. The tab sequence order is then applied to the UI element.

4.

Repeat steps 1 through 3 for each UI element whose tab sequence order value you want to change.

By default, JADE assigns a tab sequence order to UI elements as you define them on your document. Each new UI element is placed last in the tab sequence order. The valid range is any integer value.

Note UI elements are added to the document in controlList order (that is, the order in which you add them to the document). The order in this list can change during editing, because parent UI elements must always precede their children. UI elements are copied to the XAML Painter clipboard in controlList order. When pasted, each UI element has the same tab sequence order value as the original UI element. If the tab sequence order of a UI element has not been used in the new document (that is, the document on which you paste the UI element), the pasted UI element retains its tab sequence order value. A UI element pasted on to a document can therefore have a tab sequence order that differs from the one that it had on the original document, although in most cases, the tab sequence order corresponds to that of the original document (particularly when pasting controls on to new documents). Unlike JADE, the XAML Painter does not automatically renumber the tabIndex value of other UI elements to reflect insertions, deletions, and changes that would result in a tab number conflict. The tab sequence order is a guide only and JADE XAML is not affected by a number conflict. At run time, invisible or disabled controls and controls that cannot receive the focus (for example, Borders and TextBlocks) remain in the tab order but are skipped during tabbing.

Obtaining Help for a UI Element Press F1 to access the page of the PDF file that provides information about the UI element type that has focus; for example, select a combo box and then press F1. Online help that relates directly to the UI element that has focus on a document in the JADE Painter is then displayed. For example, if a TextBox control is selected, the "TextBox Class" JADE online help topic is displayed.

Defining the Layout of Your XAML Document The Layout toolbar and check boxes in the Options panel enable you to fine-tune the sizing and placement of UI elements on your painted XAML document. For example, if you have painted a row of buttons, you may want to space them neatly on your XAML document and make them all the same size.

XamlDevRef - 7.0.10


75

The Layout toolbar and check boxes in the Options panel are intended primarily for use with the Canvas UI element type.

Notes Some Layout toolbar buttons cannot be selected if you have not selected a group of two or more UI elements (that is, they are disabled). All alignments are relative to the whole XAML document unless you have selected a container, in which case alignments are relative to the container. For details, see "Adding Container UI Elements", earlier in this chapter. For those Layout toolbar buttons that align relative to a master UI element, the first UI element that you select in a group becomes the master. The master UI element is highlighted by a red border and any additional UI elements that you select have a green border. The Layout toolbar buttons can be divided into the following functions. Alignment Spacing Size

Tip Click the undo hyperlink in the Options panel, to undo the last action that you performed. For details, see "Painting Area of the XAML Painter", earlier in this chapter. To select a group of UI elements and assign a master UI element 1.

Click the first UI element of your proposed group.

2.

While holding down the CTRL key, click the other UI elements that are to be in your group.

The first UI element that you select becomes the master UI element.

Sizing Your UI Elements Use your mouse to resize UI elements on your document in the Painting area. To resize the height or width of UI elements in the Painting area 1.

Select a UI element. For details, see "Selecting a UI Element", earlier in this chapter.

2.

Position your cursor on the side of the UI element that you want to drag to resize. Your cursor then becomes a double-headed arrow.

3.

Drag the side to the require position and then release the mouse button.

To resize both height and width at the same time, move the mouse over the corner of the UI element and then drag the corner until the element is the required size. (Your cursor becomes a double-headed diagonal arrow when positioned over the corner of the element.) The Same Width and Same Height toolbar buttons, listed in the following table, enable you to standardize the size of the UI elements on your document. Toolbar Button

XamlDevRef - 7.0.10

Button Name

Description

Same Height

Makes all selected UI elements the same height

Same Width

Makes all selected UI elements the same width


76

You can also use the Size and Position dialog to scale a UI element so that it fits the current document. Before you align and space the UI elements on your document, you may want to make some elements identical in size; for example, button elements. You may also want to standardize the width or the height of other UI elements.

Tip When laying out your document, standardize the size of UI elements before using the alignment and spacing layout buttons, as the size buttons can alter the spacing of your UI elements.

Aligning Your UI Elements Use your mouse to move UI elements on your document in the Painting area. Use the check boxes in the Options panel to provide additional alignment functionality for documents that have a Canvas parent. For details, see "Options Panel Check Boxes", later in this chapter. The toolbar buttons, listed in the following table, enable you to align UI elements on your document. Toolbar Button

Button Name

Description

Align Bottom

Aligns to the bottom edge of the master UI element

Align Top

Aligns to the top edge of the master UI element

Align Left

Aligns to the left edge of the master UI element

Align Right

Aligns to the right edge of the master UI element

Vertically Adjacent

Makes the selected UI elements vertically adjacent

Horizontally Adjacent

Makes the selected UI elements horizontally adjacent

Align Centers Horizontally

Centers the selected UI elements horizontally

Align Centers Vertically


Spacing Your UI Elements The Align Bottom, Align Top, Align Left, Align Right, Vertically Adjacent, Horizontally Adjacent, Align Centers Horizontally, Space Evenly Down, and Space Evenly Across toolbar buttons enable you to neatly and logically space your UI elements across or down the document or container UI element. The Space Evenly Across, Space Evenly Down, Horizontally Adjacent, Align Centers Horizontally, and Vertically Adjacent toolbar buttons are disabled if you have not yet selected a group of controls. To enable the Space Evenly Across and Space Evenly Down toolbar buttons, you must select at least three UI elements. When using the Vertical Standard Spacing, Horizontal Standard Spacing, Vertically Adjacent, and Horizontally Adjacent commands or toolbar buttons, the position of the master control (that is, the control that is displayed with a red border) remains unchanged and not the control that is in the top or the farthest left position.

XamlDevRef - 7.0.10


77

The toolbar buttons, listed in the following table, enable you to space UI elements on your document. Toolbar Button

Button Name

Spaces the selected UI elements evenly…

Space Evenly Down

Down the container

Space Evenly Across

Across the container

Options Panel Check Boxes Check boxes in the Options panel, displayed when the options hyperlink is clicked at the upper right of the XAML Painter, are enabled only for UI elements that have a Canvas parent. The check boxes, which are unchecked by default, are listed in the following table. Check Box

Description

Grid Lines

Toggles (displays or hides) an alignment grid that has a spacing of ten pixels.

Metrics

Toggles (displays or hides) the display of additional positional information for the master control, indicating the offsets and sizes of the master selected UI element.

Snap To Grid

Snaps (moves) a selected UI element to the nearest grid intersection when the UI element is moved.

Snap To Cell

Modifies the width and height of the selected UI element to the nearest grid line (that is, sets its size to the nearest grid intersection). As this is applicable only when the Snap To Grid check box is checked, it occurs after the UI element is snapped to the nearest grid intersection.

Preview Mode

Enables interaction with the UI elements on the current document.

Direct Select

Determines the mouse interaction with a UI element by the selection rectangle rather than the visual element directly under the mouse pointer.

Lock

Toggles (enables or disables) the moving of UI elements by using the mouse (the controls can still be moved by changing positions in the property dialogs).

Using Grid Lines to Position UI Elements on XAML Documents Grid lines assist you to position UI elements on your XAML documents that have a Canvas parent. You can toggle the display of the alignment grid lines, as required. The superimposed grid lines are ten pixels apart. The alignment grid is not displayed to the user at run time. To toggle the display of alignment grid lines Check or uncheck the Grid Lines check box, to display or hide the alignment grid lines, respectively. To specify additional grid lines and alignment options 1.

Check the Snap To Grid check box if you want to control the placement of your UI elements. When this check box is checked, the alignment grid lines dictate the placement and movement of UI element on your document, and elements snap to the nearest position on the grid even when the grid is not displayed.

2.

Check the Snap To Cell check box and the Snap To Grid check box if you want to control the placement and

XamlDevRef - 7.0.10


78

size of your UI elements. When both these check boxes are checked, the grid lines dictate the placement, movement, and size of the UI elements on your document, and snap to the nearest position on the grid and the width and height are resized to the nearest grid line even when the grid is not displayed.

Note The Snap To Cell check box has no effect unless the Snap To Grid check box is also checked. 3.

Check the Metrics check box, to display additional positional information about the master control, including offset and size, of the selected UI element.

The following diagram shows an example of the alignment grid lines and measurements that are displayed on a document.

Note The Grid UI element is a powerful layout manager that can resize and arrange child elements automatically. For details, see "Grid UI Element Type", in Chapter 4.

Locking the Position of UI Elements on Your Document Check the Lock check box, displayed when the options hyperlink is clicked, to lock all of the UI elements on your document so that you cannot accidentally move them by dragging. To lock all UI element positions Check the Lock check box.

Direct Select Functionality The Direct Select check box, displayed when the options hyperlink is clicked, determines the mouse interaction with a UI element by the selection rectangle rather than the visual element directly under the mouse pointer. If you select a UI element, check the Direct Select check box, and then click within the boundary of the current selection rectangle, that UI element will continue to be selected even if you click on another UI element. If you do not check the Direct Select check box, the UI element that is currently under your cursor is selected when you click the left mouse button.

XamlDevRef - 7.0.10


79

To use the direct select function Check the Direct Select check box.

Previewing UI Elements on Your Document The Preview Mode check box, displayed when the options hyperlink is clicked, enables you to test the UI elements painted on a XAML document; for example, you can enter text into a text box, click a button, or test the tabbing order. To preview UI elements on your document Check the Preview Mode check box.

XamlDevRef - 7.0.10


80

Examples of Laying Out UI Elements The following example shows the use of the layout toolbar buttons to arrange the buttons on a XAML document. The buttons were all selected and then made the same size by using the Same Height and Same Width toolbar buttons.

With the buttons still selected (and Btn_Button2 as the master selection), use the Vertically Adjacent toolbar button to align your controls, as shown in the example in the following diagram.

Finally, you can then space the selected buttons neatly across the document, by using the Space Evenly Across toolbar button, as shown in the example in the following diagram.

Note In this example, the buttons have been moved relative to the whole XAML document. If they had been part of a container UI element, they would have been spread evenly relative to the container, not the XAML document.

XamlDevRef - 7.0.10


81

Maintaining Properties for Your XAML Document or UI Element To maintain the properties associated with your document or UI element, use the dialogs in the Properties area at the left of the XAML Painter. Alternatively, edit the XAML code of the UI element attribute directly in the XAML View sheet.

Note If you edit the XAML code directly, ensure that you are making valid changes. If you attempt to load invalid XAML, the XAML Painter may not be able to catch any exceptions raised by the Silverlight plug-in. In the worst case, Silverlight does not raise an exception that the XAML Painter can catch; it simply crashes and you must restart the XAML Painter. The dialogs that are displayed in the Properties area depend on the type of UI element that you select. In general, there are six dialogs covering the various properties. Most of the properties have default settings and many property values are set automatically when you manipulate your document or UI elements in the Painting area or you use some of the layout and alignment options. If the label of a property in a dialog is truncated, as the HorizontalAlignment and VerticalAlignment labels are in the following diagram, click on the light-blue line at the right of the labels and then drag it farther to the right until the whole label is displayed.

For all XAML classes, the unit of measurement for widths, heights, radius, and so on, is the device-independent pixel. For details about specific document and UI element properties, see your JADE Encyclopaedia of XAML Classes. The XAML property values and terms with which you may be unfamiliar are: Thickness, which is a unit of measurement that describes the thickness of a frame or border around a UI element. This is typically used when describing a margin or padding, but it is used in other situations for different UI elements. Thickness relates to four measurements (left, top, right, and bottom) that you can define in the property dialogs or in XAML in the styles listed in the following table. Margin Value

Description

10

Uniform, which is applied to all four thickness measurements; that is, all sides will have a margin of 10

10,20

The first value is applied to the left and right margins, the second value to the top and bottom margins

10,20,5,15

Asymmetric margins; that is, left = 10, top = 20, right = 5, and bottom = 15

XamlDevRef - 7.0.10


82

Whichever method you use to set the margin, the display value is displayed in the asymmetric format. NaN, which is a unit that represents that a value is not a number. It is typically seen when the numeric attribute has been removed from the XAML. When the value of that numeric property is queried, it responds that it is NaN – not set. This is typically done when you want a parent container to manage the size of a child UI element. By removing the size attribute from the child, you allow the parent to size the child, potentially adjusting the size of the child as the parent itself resizes. (A Canvas parent does not adjust the size of its child elements.) To remove the attribute from the XAML, clear the value in the property dialog and press ENTER, to update the XAML. This removes the attribute from the XAML, leaving a blank property field until next refreshed, at which time it will display NaN; for example, if the Height value is NaN, the attribute is not defined in the XAML and its value is not a number. Infinity, which is a unit that represents that a value is positive or negative infinity. It is typically seen as the default value for items such as MaxHeight; for example, if the MaxHeight value is Infinity, this provides a maximum value for an item (in this example, the MaxHeight for the control does not need to be considered by the layout manager).

Maintaining General Properties Use the General Properties dialog of the Properties area to define the common properties for your document or selected UI element. The properties that you can maintain depend on the document or selected UI element. For details about using the Name text box in the General Properties dialog, see "Naming a UI Element", earlier in this chapter. For details about specific document and UI element properties, see the JADE Encyclopaedia of XAML Classes. To change the general properties of your document or selected UI element 1.

Select the UI element whose properties you want to change. For details, see "Selecting a UI Element", earlier in this chapter. The dialogs in the Properties area then display the properties associated with the UI element.

2.

If a text box is associated with the property, make your change by overwriting the existing value in the text box.

3.

If a list box is associated with the property, click on the list box and then make your selection from the menu that is displayed.

To change the parent of a UI element 1.

Select the UI element whose parent you want to change. For details, see "Selecting a UI Element", earlier in this chapter.

2.

In the Parent combo box in the General Properties dialog, select the UI element that you want the selected UI element to reference at run time. The current parent of the selected UI element is displayed in the Parent combo box.

Note The display properties of a UI element are relative to the parent UI element. Changing the parent of a UI element affects the placement and visibility of the child UI element.

XamlDevRef - 7.0.10


83

Maintaining Size and Position Properties Use the Size and Position dialog of the Properties area, accessed by clicking the expand icon at the upper left of that dialog, to change the size and position of UI elements within your document or another UI element. The size and position properties that you can maintain depend on the type of UI element that you select. An example of the Size and Position dialog for a Button is shown in the following diagram.

To change the Size and Position properties of your document or UI element 1.

Click the property that you want to change. The property is then highlighted, enabling you to specify the required size and position in the associated text boxes and combo boxes.

2.

Make your change by overwriting the existing value in the text box, or by selecting the required value in the list box.

Additionally, you can use the Layout toolbar to size and align selected UI elements or groups of UI elements. For details, see "Layout Toolbar", later in this chapter. For details about specific document and UI element properties, see the JADE Encyclopaedia of XAML Classes.

Maintaining Colors and Styling Properties Use the Colors and Styling dialog of the Properties area, accessed by clicking the expand icon at the upper left of that dialog, to change the color and style properties of your document or UI element.

XamlDevRef - 7.0.10


An example of the Colors and Styling dialog for a Button is shown in the following diagram.

To change the color and style properties of your document or UI element 1.

Click the property that you want to change. The property is then highlighted, enabling you to specify the required font attributes in the associated text boxes or combo boxes.

2.

Make your change by overwriting the existing value in the text box, or selecting the required value in the combo box.

Selecting a Color To select a color property for a UI element 1.

Click in the combo box of the UI element property whose color you want to change; for example, the Background combo box.

2.

To make the UI element transparent, select the Transparent item. Alternatively, to select a color for the UI element, select the Color selector item. The screen shown in the following diagram is then displayed.

XamlDevRef - 7.0.10

84


85

The Colors by Hue sheet, shown in the previous diagram, is displayed by default. The Colors by Name sheet enables you to select a color by name (for details, go to step 4, later in this instruction). The currently selected color is displayed at the bottom of the screen, where the Cancel and OK buttons are. 3.

To use the Colors by Hue sheet to select a color: a.

Perform one of the following actions. In the R, G, and B fields, specify the color in terms of the proportions of red, green, and blue, respectively. Specify a value between 255, the maximum, and zero (0), the minimum, in each field. In the HEX field, enter the color as a hexadecimal value. Select the color by using the color palette, at the left of the sheet. At the right of the color palette, drag the slider, indicated by two black triangles, to the required hue. Click in the circle at the left of the color palette and drag it to the required position, to change the saturation (x-axis) and brightness (y-axis) accordingly.

b.

The A field (alpha channel) enables you to specify the opacity of the color. A value of 255 means totally opaque and zero (0) means totally transparent.

The selected color is displayed at the bottom of the screen, where the Cancel and OK buttons are. 4.

To select a color by name: a.

Click on the Colors by Name tab to display the Colors by Name sheet, shown in the following diagram.

b.

By default, the colors are listed in alphabetical order. To list the colors from dark to light, check the Sort dark to light check box that is displayed at the bottom of the screen.

c.

Click on the color that you want to select.

The selected color is displayed at the bottom of the screen, where the Cancel and OK buttons are. 5.

Click the OK button, to select that color. Alternatively, click the Cancel button, to abandon your selection.

The selected color is then displayed in the combo box in the Colors and Styling dialog. For details about specific document and UI element properties, see the JADE Encyclopaedia of XAML Classes.

XamlDevRef - 7.0.10


86

Maintaining Font Properties Use the Fonts dialog of the Properties area, accessed by clicking the expand icon at the upper left of that dialog, to change the font of your document or UI element. An example of the Fonts dialog is shown in the following diagram.

To change the font of your document or UI element 1.


2.

Make your change by overwriting the existing value in the text box, or selecting the required value in the combo box.

For details about specific document and UI element properties, see the JADE Encyclopaedia of XAML Classes.

Maintaining Grid Definitions Use the Grid Definition dialog, accessed by clicking the expand icon at the upper left of that dialog, to maintain the grid layout of XAML documents that are based on the following styles. Grid Based - Sizeable, Scrollable Grid Based - Fixed Size, Scrollable Grid Based - Fixed Size Child Window The grid is the most powerful of the layout managers. It is designed to be used for the layout of the user interface of your applications and is not intended for data display (for displaying data in a tabular fashion, you would typically use a XamlDataGrid). By default, a grid has one row and column. It is at its most useful when it contains multiple rows and columns in which the resulting cells manage the position and size of the child controls.

XamlDevRef - 7.0.10


87

The following diagram shows an example of the Grid Definition dialog.

Key to the flexibility of the grid are the unit of measurement options that are available when defining width and height. These options are: Integer, where the value is defined in pixels Auto, where the size is determined by the size properties of the content object Asterisk (*), where the value is expressed as a weighted proportion of available space For details about defining a grid, see "Grid UI Element Type", in Chapter 4. For details about specific document and UI element properties, see the JADE Encyclopaedia of XAML Classes.

Maintaining Miscellaneous Properties Use the Miscellaneous dialog of the Properties area, accessed by clicking the expand icon at the upper left of that dialog, to maintain miscellaneous properties of your document or UI element.

XamlDevRef - 7.0.10


88

The properties that you can maintain depend on the UI element that you select. The Miscellaneous dialog example shown in the following diagram is for a TextBox UI element.

To maintain miscellaneous properties of your document or UI element 1.


2.

Make your change by overwriting the existing value in the text box, or by selecting the required value in the combo box.


Maintaining Transformations Use the Transformations dialog of the Properties area, accessed by clicking the expand icon at the upper left of that dialog, to transform your document or UI element. For example, you can rotate a UI element by a specified number of degrees. An example of the Transformations dialog is shown in the following diagram.

XamlDevRef - 7.0.10


89

To transform your document or UI element 1.


2.

Make your change by overwriting the existing value in the text box, or by selecting the required value in the combo box.


Defining Methods for Your Document To define methods to support your documents and UI elements, see the JADE Encyclopaedia of XAML Classes.

Saving Your Document To save your XAML document, perform one of the following actions Select the Save command from the XAML menu. Press CTRL+S. For details, see "Saving Your Document", in Chapter 2. When you save your document in the XAML Painter, any single quote characters (') in the XAML are converted to the string ' when you view that document in the XAML Browser. Single quote characters are not allowed in the XAML Browser and must be replaced with the string ' so that the XAML remains valid. To save your XAML document under a different name Select the Save As command from the XAML menu. The Save Document-name as dialog is then displayed. For details, see "Saving Your Document as another Name", in Chapter 2. The Save As command is disabled if you have changed the document without saving it. After you save your changes, the Save As command is enabled.

Editing an Existing Document in the XAML Painter To load an existing document so that you can maintain it Select the Edit command from the XAML menu of the Painter.

XamlDevRef - 7.0.10


90

The Edit Xaml Document dialog, shown in the following diagram, is then displayed to enable you to specify the name of the document that you want to load for editing.

To load an existing document 1.

From the text area of the Document combo box, specify the name of the document that you want to edit or select the document from the list box. The list box area of the Document combo box displays the XAML documents defined for the currently selected schema.

2.

Click the OK button. Alternatively, click the Cancel button to abandon your selection.

Using the Keyboard and Mouse to Edit Your Document When the selected document has been loaded, use combinations of keyboard and mouse actions to manipulate the UI elements on the document in the Painting area or edit the XAML directly on the XAML View sheet. You can also change details of a UI element or a group of UI elements by using the Properties dialog. For details, see "Maintaining Properties for Your XAML Document or UI Element", earlier in this chapter. For details about changing the type of an existing UI element (for example, changing a ComboBox UI element to a TextBox UI element), see "Changing a UI Element Type", later in this chapter. UI elements in the document are made visible and are enabled in the XAML Painter only if the settings of the IsHitTestvisible and the IsEnabled properties of each UI element are set to True. However, a UI element inherited from a superclass document is disabled, regardless of the setting of the IsEnabled property of that UI element on the current document. This provides you with a visual indicator in the XAML Painter that you cannot edit the UI element on the current document, as it belongs to the document of a superclass.

Selecting Multiple UI Elements To select multiple UI elements in the Painting area Click on each UI element to be selected, while holding down the CTRL key. The first (master) element that you selected is highlighted with a red border. Subsequent selections have a green border. For details, see "Selecting a UI Element", earlier in this chapter.

XamlDevRef - 7.0.10


91

To deselect a UI element that is already selected While holding down the CTRL key, click on the UI element that you do not require in the selection.

Changing the Size of Selected UI Elements To change the size of all selected UI elements Drag a side or a corner on the master UI element.

Moving UI Elements around Your Document To move one or more selected UI elements around your document Drag the UI element or selected UI elements that you want to move. All selected UI elements move during the drag operation. If the UI element move lock operation is on (that is, you checked the Lock check box in the Options panel), you cannot move any UI elements.

Notes You can select the base element of the document (typically the background or root element) but you cannot move it by dragging it. To move or resize a base element, use the Size and Position property dialog. When you add a UI element to a cell in a grid-based XAML document, its Margin property is set to 0,0,0,0. If you then drag that element to another part of the same cell, the XAML Painter sets the Margin property so that the element retains that position within the cell. This causes the underlying grid to change the size of the columns and rows: it does not affect the size of the document, only the grid layout. This behavior is a restriction of Silverlight that JADE is unable to change. Manually control the layout by setting the size of the columns and rows of the grid as required. For details, see "Grid UI Element Type", in Chapter 4.

Copying UI Elements To copy a one or more selected UI elements that have the same parent Hold down the CTRL+ALT keys and then drag the selected UI element or UI elements to the new location on the document.

Displaying the Properties for a UI Element To display the Properties for a UI element Select that UI element. For details, see "Selecting a UI Element", earlier in this chapter. The Properties area then displays details of the selected UI element. You can use the Properties area to change the UI element whose details are displayed, if required. That UI element then becomes the selected UI element on the document that you are editing.

Placing a UI Element on a Container UI Element Container UI elements (for example, a canvas or stack panel) allow you to place other UI elements on top of them.

XamlDevRef - 7.0.10


92

To place a UI element on a container 1.

Select the container element to which you want to add a child element.

2.

Add the UI element as you would when adding a UI element to the document. For details, see "Adding UI Elements to Your Document", earlier in this chapter.

A UI element that is positioned on a container UI element becomes a child UI element of the container, or parent, UI element. The position coordinates of a child UI element are always relative to its parent UI element. Child UI elements remain relative to the parent so that they move if the parent UI element moves. To change the parent of a UI element Select the parent in the Parent combo box in the General Properties dialog in the Properties area.

Removing a UI Element from Your Document Before deleting one or more UI elements, ensure that you have selected the correct UI elements. You cannot delete a UI element that is inherited from a super document. If the selected UI element is not referenced in any JADE methods, it is unconditionally deleted. If the selected UI element is referenced by one or more JADE methods, a message box is displayed, as shown in the following diagram, after you try and save the document.

Click the Yes button to confirm the deletion of the current UI element. Alternatively, click the No button to cancel the deletion request. To delete a UI element from a document Select the UI element that you want to delete and then press the DELETE key, or click the delete hyperlink in the options panel. Delete the relevant XAML code in the XAML View sheet and then click the Load XAML button. If you deleted the wrong UI elements and have not yet saved your changes, select the Refresh command in the XAML menu, to restore the document to the previously saved version.

Changing a UI Element Type You can change the type of a UI element on a document, providing that the change does not break any rules regarding the UI element that can be the parent and the type of child UI elements that are permitted.

XamlDevRef - 7.0.10


93

The UI element name, event method code, and so on, are retained, so that you do not have to first delete the existing UI element, add the replacement UI element of the required type, and then create the appropriate event methods. To change the existing type of a UI element selected on a document Manually edit the XAML on the XAML View sheet.

Note If you edit the XAML code directly, ensure that you are making valid changes. If you attempt to load invalid XAML, the XAML Painter may not be able to catch any exceptions raised by the Silverlight plug-in. In the worst case, Silverlight does not raise an exception that the XAML Painter can catch, it simply crashes and you must restart the XAML Painter.

Effects of Editing an Existing Document If the document that you are editing is being used at run time, you are warned that the document cannot be saved until no user is using the document. If you try to save the edited document, the save action is disallowed until the document is not being used. When you access an existing document in the XAML Painter, you automatically lock the document class. Although locking a document prevents other users from making changes, they can view the unchanged document. When you exit from Painter, the lock is released.

Deleting a Document Use the Delete command from the XAML menu to delete a document. To delete a document 1.

Select the Delete command from the XAML menu. A message box is then displayed, prompting you to confirm that you want to delete the selected document.

2.

Click the Yes button to delete the document. Alternatively, click the No button to abandon the deletion.

Notes You cannot delete a document if the document has subclasses, any existing property references, or the document is open in the XAML Browser. When you delete a document, the corresponding class and all of its methods are deleted. Any methods referencing the deleted document are flagged as uncompiled.

Layout Toolbar The buttons in the Layout toolbar enable you to size and align selected UI elements or groups of UI elements that have the same parent. The Layout toolbar is intended primarily for use with the Canvas UI element type. Before you align and space the UI elements on your document, you may want to make some elements identical in size; for example, button elements. You may also want to standardize the width or the height of other UI elements. The Layout toolbar buttons normally operate only on UI elements that are in the same container.

Tip When laying out your document, standardize the size of UI elements before using the alignment and spacing layout buttons, as the size buttons can alter the spacing of your UI elements.

XamlDevRef - 7.0.10


94

The Layout toolbar buttons are listed in the following table. Toolbar Button

Button Name

Description

Align Bottom

Aligns to the bottom edge of the master UI element

Align Top

Aligns to the top edge of the master UI element

Align Left

Aligns to the left edge of the master UI element

Align Right

Aligns to the right edge of the master UI element

Vertically Adjacent

Makes the selected UI elements vertically adjacent

Horizontally Adjacent

Makes the selected UI elements horizontally adjacent

Align Centers Horizontally


Align Centers Vertically


Space Evenly Down

Spaces the selected UI elements evenly down the container

Space Evenly Across

Spaces the selected UI elements evenly across the container

Same Height

Makes all selected UI elements the same height

Same Width

Makes all selected UI elements the same width

You cannot select the Align Bottom, Align Top, Align Left, Align Right, Vertically Adjacent, Horizontally Adjacent, Space Evenly Down, Space Evenly Across, Same Height, or Same Width button if you have not yet selected a group of UI elements (that is, they are disabled). To select a group of UI elements and assign a master UI element 1.

Click the first UI element of your proposed group.

2.

While holding down the CTRL key, click the other UI elements that are to be in your group.

The first UI element that you select becomes the master UI element and all other elements are aligned or sized relative to the master UI element. For details, see "Selecting a UI Element", earlier in this chapter.

Align Bottom Button Use the Align Bottom button in the Layout toolbar to align a group of UI elements so that the bottom edges of the selected UI elements are aligned with that of the master UI element. To align the bottom edges of the selected UI elements 1.

Select the UI elements whose bottom edges you want to align. (Select the UI element with which you want to align the other elements first.)

XamlDevRef - 7.0.10


2.

95

Click the Align Bottom toolbar button.

Align Top Button Use the Align Top button, in the Layout toolbar, to align a group of UI elements so that the top edges of the selected UI elements are aligned. To align the top edges of the selected UI elements 1.

Select the UI elements whose top edges you want to align. (Select the UI element with which you want to align the other elements first.)

2.

Click the Align Top toolbar button.

Align Left Button Use the Align Left button in the Layout toolbar to align a group of UI elements so that the left edges of the selected UI elements are aligned. To align the left edges of your selected group of UI elements 1.

Select the UI elements whose left edges you want to align. (Select the UI element with which you want to align the other elements first.)

2.

Click the Align Left toolbar button.

Align Right Button Use the Align Right button in the Layout toolbar to align a group of UI elements so that the right edges of the selected UI elements are aligned. To align the right edges of the selected UI elements 1.

Select the UI elements whose right edges you want to align. (Select the UI element with which you want to align the other elements first.)

2.

Click the Align Right toolbar button.

Vertically Adjacent Button Use the Vertically Adjacent button in the Layout toolbar to align UI elements vertically. The highest UI element that you select does not move when the Vertically Adjacent button is clicked. All of the selected UI elements (except for the highest UI element) are moved upward. UI elements that are in different horizontal parts of the document are moved and they become adjacent along a vertical axis. To select this button from the Layout toolbar, you must first select a group of two or more UI elements. To make your selected UI elements vertically adjacent 1.

Select the UI elements that you want to be vertically adjacent.

2.

Click the Vertically Adjacent toolbar button.

XamlDevRef - 7.0.10


96

Horizontally Adjacent Button Use the Horizontally Adjacent button in the Layout toolbar to align UI elements horizontally. The UI element farthest to the left does not move when the Horizontally Adjacent button is clicked. All of the selected UI elements (except for the farthest left) are moved to the left. UI elements that are in different vertical parts of the document are moved and they become adjacent along a horizontal axis. To select this button from the Layout toolbar, you must first select a group of two or more UI elements. To make your selected UI elements horizontally adjacent 1.

Select the UI elements that you want to be horizontally adjacent. (Select the UI element with which you want to align the other elements first.)

2.

Click the Horizontally Adjacent toolbar button.

Align Centers Vertically Button Use the Align Centers Vertically button in the Layout toolbar to center a UI element or group of UI elements relative to the vertical axis of your document or container UI element. To center the selected UI elements vertically 1.

Select the UI elements that you want to center vertically.

2.

Click the Align Centers Vertically toolbar button.

The selected UI elements do not move relative to each other. If you select one UI element only, it centers only that UI element.

Align Centers Horizontally Button Use the Align Centers Horizontally button in the Layout toolbar to center a UI element or group of UI elements relative to the horizontal axis of your document or container UI element. To center the selected UI elements horizontally 1.

Select the UI elements that you want to center horizontally.

2.

Click the Align Centers Horizontally toolbar button.

The selected UI elements do not move relative to each other. If you select one UI element only, it centers only that UI element.

Space Evenly Down Button Use the Space Evenly Down button in the Layout toolbar to space a group of UI elements so that the vertical distance between each UI element is the same. The Space Evenly Down toolbar spreads the selected UI elements evenly down the whole document or container.

XamlDevRef - 7.0.10


97

To space the UI elements evenly down the document or container 1.

Select the UI elements that you want to space evenly down the document or container.

2.

Click the Space Evenly Down toolbar button.

Space Evenly Across Button Use the Space Evenly Across button in the Layout toolbar to space a group of UI elements so that the horizontal distance between each UI element is the same. The Space Evenly Across toolbar spreads the selected UI elements evenly down the whole document or container. To space the UI elements evenly across the document or container 1.

Select the UI elements that you want to space evenly down the document or container.

2.

Click the Space Evenly Across toolbar button.

Same Width Button Use the Same Width button in the Layout toolbar to standardize the width of two or more selected UI elements. The UI elements that you select are assigned a width equal to the selected master UI element. Width truncation or extension is performed from the right. To standardize the width of the selected UI elements 1.

Select the UI elements that you want to make the same width. (Select the UI element with which you want to standardize the widths of the other elements first.)

2.

Click the Same Width toolbar button.

Same Height Button Use the Same Height button in the Layout toolbar to standardize the height of two or more selected UI elements. The UI elements that you select are assigned a height equal to the selected master UI element. Height truncation or extension is from the bottom. To standardize the height of the selected UI elements 1.

Select the UI elements that you want to space evenly down the document or container. (Select the UI element with which you want to standardize the heights of the other elements first.)

2.

Click the Same Height toolbar button.

XamlDevRef - 7.0.10

Chapter 4

Considerations When Developing Silverlight Applications

This chapter covers the following topics. Using Third-Party Controls Third-Party Control Usage in JADE Silverlight Stateful Applications Third-Party Control Usage in JADE Silverlight Stateless Applications Abstract Classes and Third-Party Controls Accessing .NET Objects Accessing Silverlight Fields and Properties Accessing Silverlight Methods Specifying a Type Enums Using Layout Manager UI Element Types Canvas UI Element Type StackPanel UI Element Type Grid UI Element Type Using Resources in XAML Documents Creating Controls Dynamically or from a Template Use of the itemsSource Property by Different XAML Classes XamlSelector and XamlDataGrid Class Use of the itemsSource Property XamlAutoCompleteBox Use of the itemsSource Property Unit Testing Silverlight Applications Adding Silverlight Unit Tests to the JADE Unit Testing Framework Running the Silverlight Application Unit Tests

Using Third-Party Controls This section describes how to use third-party controls in your JADE Silverlight stateful and stateless applications.

Third-Party Control Usage in JADE Silverlight Stateless Applications The examples in this section use the ButtonSpinner control from the Microsoft Silverlight toolkit.

XamlDevRef - 7.0.10

XAML Developer's Reference Chapter 4 Considerations When Developing Silverlight Applications

99

Before the XAML that contains the control can be used, the DLLs defining the control must be available for JADE. You can place these DLLs in one of the following locations. The bin directory of your application server. In a folder that is referred to by the DefaultAssemblyLocation parameter in the [JadeSilverlight] section of the JADE initialization file. To use the controls in your XAML, you must add the correct namespace declaration at the end of the opening element of your XAML; for example, add the following to the end of the first element of the XAML. The ButtonSpinner control can then be used from this assembly, by adding a control element; for example: When the XAML is saved, in the XamlDocument subclass (created for the XAML), you will find a reference of type XamlObject, with the name specified in the control element (in this case, spinner) that is the JADE reference to the control. You can use this reference to access properties and call methods of the control. You can use the XamlObject class setXamlProperty, getXamlProperty, invokeXamlMethod, and invokeXamlMethodio methods to manipulate the control object; for example, to access the properties and methods of the event arguments. To determine what is available, consult the documentation of the third-party control. To receive events from the controls, use the XamlDocument class registerEventHandler method to register for event notification. Using the ButtonSpinner in the previous example, call the registerEventHandler method to register for the "Spin" event; for example: registerEventHandler(spinner, "Spin", ThirdPartyControls::spinnerSpun); The first parameter indicates the control with which we are working, the second is the event name of the control, and the last parameter is the JADE method that will be called when this event is triggered. The JADE method that handles the event (the event handler method) must have the following signature. (sender:XamlObject input; eventArgs:XamlObject) browserExecution; The following example of an event handler for a button spinner also demonstrates the use of the getPropertyValue and setPropertyValue methods. spinnerSpun(control XamlObject input; eventArgs:XamlObject) browserExecution; vars i : Integer; spinDirection : String; begin spinDirection := eventArgs.getXamlProperty("Direction").String i := control.getXamlProperty("Content").Integer; if spinDirection = "Increase" then i := i+1; else i := i-1; endif; control.setXamlProperty("Content", i); end;

XamlDevRef - 7.0.10


100

The Silverlight controls implemented in JADE are built on controls that are available in standard Silverlight. The supporting Silverlight DLLs contain many more controls than those exposed by JADE. The other controls in these DLLs can also be accessed in a similar way to that described in this section. However, for controls not exposed by JADE, you do not have to place a copy of the DLL in the JADE bin directory or default assembly location, as JADE will already know how to find these. Depending on the control that you use, it may be unnecessary to include a namespace declaration.

registerEventHandler Method for DataTemplate Controls To generically handle the XamlDocument class registerEventHandler method for controls defined in a DataTemplate: When you save a document, any third-party controls are investigated to determine where they fit in the JADE XamlObject hierarchy. (These controls are not generated as a XamlObject-type property.) When you save a document, the assemblies for that control are referenced to determine whether the control inherits from a JadeXamlControl type; for example, the RadComboBox in the Telerik Controls assembly inherits from XamlItemsControl. As a result, the property associated with that control is created as a XamlItemsControl. This also means that the control can be referenced via the property, as that type and the events associated with that control type can be directly defined rather than having to call the XamlDocument class registerEventHandler method.

Note Any assemblies required must be located in the directory associated with the DefaultAssemblyLocation parameter in the [JadeSilverlight] section of the JADE initialization file. If the required assemblies cannot be found, a message box advises you of the failure and asks if you want to display the details in an exception dialog. The exception dialog lists the assembly that could not be found. A named item in a DataTemplate is generated as a virtual property of the defined type, which enables you to directly define events in JADE. However, because it is virtual, any logic references will be rejected by the JADE compiler. This is deliberate, because at run time, the template can be used multiple times to generate different instances of the control that all have the same name. When an event occurs on one of these controls, the first parameter of the event is the control instance, which can then be referenced in logic. For third-party controls used that are named and can be defined as a XamlUIElement subclass, you can define events not available in JADE by performing the following actions. 1.

Define an event handler method for the event. In the following example, the source type matches the type of the control property. radCombo_selectionChanged(source: XamlItemsControl input; origin: XamlObject input);

2.

Define a loaded event on the control in JADE that does the following (where the source type matches the type of the control property). radCombo_Loaded(control: XamlItemsControl input; originalSource: XamlObject input); begin if control.tag "Done" then // The loaded event for a control // can be called multiple times if // the control is hidden and then // made visible, for example.

XamlDevRef - 7.0.10


101

self.registerEventHandler(source, "SelectionChanged", xaml-document-name::radCombo_selectionChanged); control.tag := "Done"; endif; endif; This logic will then register that event for every instance of the DataTemplate item that is created.

Third-Party Control Usage in JADE Silverlight Stateful Applications This section describes how to use third-party controls (or Silverlight controls not exposed by JADE) in your JADE Silverlight stateful applications. The following examples use the Expander control from the Microsoft Silverlight toolkit. The JADE Silverlight runtime JadeAGL needs to be given the assembly (or assemblies) that define the control. To use these controls, the associated assemblies must be available to the application server for downloading to the XAML Painter. Before loading the XAML that contains the control, call the XamlManager class loadAssembly or loadAssemblyFromBinary method to pass the assembly on to JadeAGL, as follows. app.xamlManager.loadAssembly("System.Windows.Controls.Toolkit.dll"); You must add valid XAML that uses the control directly into the XAML editing area of the XAML Browser or XAML Painter. You cannot use the Painting area of the XAML Painter to add these controls, as it does not know about them. To use the third-party control in your XAML, perform the following actions. 1.

Add the correct namespace declaration at the end of the first element of your XAML, if the namespace of the control is not already included; for example:

2.

Insert valid XAML at the required location in your XAML; for example:

You should now be able to run the XAML application in the usual way and find a functioning external control on that document. Manipulate the Silverlight control object by calling the XamlObject class setXamlProperty, getXamlProperty, invokeXamlMethod, and invokeXamlMethodio methods.

Abstract Classes and Third-Party Controls Brush, Geometry, Panel, RangeBase, Selector, Shape, Transform, and UIElement are abstract classes in Silverlight but they are not abstract in the JADE XAML framework. If you import a third-party Silverlight control that is a subclass of one of those classes, the representation of this control is an instance of one of these abstract Silverlight classes. These classes are therefore not abstract in the RootSchema; that is, there might be real instances of them.

XamlDevRef - 7.0.10


102

You cannot create instances by user logic for these classes because this results in an exception.

Accessing .NET Objects The XamlObject class provides the following methods that support access to underlying .NET objects, usually defined in third-party DLLs. getXamlProperty setXamlProperty invokeXamlMethod invokeXamlMethodio These methods are called on a JADE object that is acting as a proxy for a .NET or Silverlight object. The first parameter of these methods specifies the member of the underlying .NET object that is to be accessed or invoked.

Accessing Silverlight Fields and Properties Call the XamlObject class getXamlProperty and setXamlProperty methods to access Silverlight fields and properties. The first parameter of each method specifies the name of the field or property of the current .NET object being accessed. To access a static type that is not the type of the current .NET object, see "Specifying a Type", later in this chapter. Enumerated (enum) type values are passed as strings. The string value passed is one that matches the string constant of the enum value. For details, see "Enums", later in this chapter.

Accessing Silverlight Methods Call the invokeXamlMethod or invokeXamlMethodio method to access a Silverlight method. The first parameter of each method specifies the name of the method of the current .NET object being invoked. If the .NET method being invoked has: No parameters or input parameters only, use the invokeXamlMethod method. Reference or output parameters, you must use the invokeXamlMethodio method. To access a static method on a type that is not the type of the current .NET object, see "Specifying a Type", later in this chapter. Enum values are passed as strings. The string value passed is one that matches the string constant of the enum value. For details, see "Enums", later in this chapter.

Overloaded .NET Methods If the .NET method is overloaded, the first parameter must also specify the arguments of the method, to identify the correct method to invoke, as shown in the following examples. invokeXamlMethod("Mth(Int32)", arg); invokeXamlMethod("Mth(System.Int32)", arg);

XamlDevRef - 7.0.10


103

Prefix the types in the method with ref (for reference parameters) or out (for output parameters), as appropriate, as shown in the following example. invokeXamlMethod("Mth(ref Int32; out Int32)", arg1, arg2); If you specify more than one parameter in a method, separate each parameter with a semicolon character, as shown in the previous example. Types from the system namespace do not need to specify their namespace. Other types, however, must be an assembly-qualified name, as shown in the following example. For details, see "Specifying a Type", later in this chapter. invokeXamlMethod(("Mth(" & aqn & ")").StringUtf8, arg);

Note In the previous example, aqn is an assembly-qualified name of the parameter type.

Constructors Constructors can be called by specifying the special method name .ctor, which must be prefixed by the type of the object being constructed, as shown in the following example. For details, see "Specifying a Type", later in this chapter. invokeXamlMethod((aqn&";.ctor").StringUtf8); Overloaded constructors are called in the same way as normal overloaded methods, as shown in the following example. invokeXamlMethod((aqn&";.ctor(Int32)").StringUtf8, 64);

Note In the previous example, aqn is an assembly-qualified name of the parameter type.

Specifying a Type When it is necessary to specify the type for static member access or for method parameter specification, a fullyqualified name is required. The fully-qualified name is defined in .NET and must conform to the .NET expectations. It has the following format. ., For more details, see your .NET documentation. If you specify a fully-qualified name in the getXamlProperty, setXamlProperty, invokeXamlMethod, or invokeXamlMethodio method, separate the type and member with a semicolon character, as shown in the following example. invokeXamlMethod((aqn&";.ctor").StringUtf8);

Enums Enums are passed between .NET and JADE as strings. The string value corresponds to the name of the constant defined in the .NET enum. For example, where the property MyProp is of type Days, the: C# enum definition is as follows. public enum Days {

XamlDevRef - 7.0.10


104

Saturday, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday }; Corresponding JADE enum access code is as follows. setXamlProperty("MyProp", "Monday"); getXamlProperty("MyProp"); If the enum is a flags type (that is, it has the FlagsAttribute attribute), multiple values can be set by providing a comma-separated list. For example, where the property MyProp is of type Direction, the: C# enum definition is as follows. public enum AllowedDirection { None = 0x0, Up = 0x1, Down = 0x2, Left = 0x4, Right = 0x8 } Corresponding JADE enum access code is as follows. setXamlProperty("MyProp", "Up, Down");

Using Layout Manager UI Element Types The Canvas, StackPanel, and Grid UI elements are types of Panel, which is a layout manager type of UI element. Panels are designed to hold multiple UI elements. The layout of UI elements within the Panel depends on the type of Panel, as each Panel type exerts its own layout requirements on the UI elements it contains.

Note Layout managers can contain other layout managers; for example, a canvas can contain a grid, and so on. This section covers the following layout managers. Canvas StackPanel Grid The following table summarizes the differences and similarities between the layout manager types. Canvas

StackPanel

Grid

Grid-based layout?

No

No

Yes

Child elements added

At upper left

In the next available stack position

In specified grid cell

Child elements can be

No

No

Yes resized automatically?

Child elements can overlap?

Yes

No

Yes

Uses zIndex?

Yes

No

No

For details, see the following subsections.

XamlDevRef - 7.0.10


105

Canvas UI Element Type The Canvas is the most simple of the layout managers, and is considered a layout manager only because the children you position on it move with the Canvas. The Canvas parent does not exert any influence over the size of its children if it is resized. In addition, children can overlap and be placed outside or extend beyond the boundaries of the parent (the children always move relative to the Canvas if the parent is moved). In addition, the Layout toolbar and check boxes in the Options panel are intended primarily for use with children on the Canvas UI element. For details, see "Defining the Layout of Your XAML Document" and "Options Panel Check Boxes", in Chapter 3. An additional attribute, the zIndex, is unique to UI elements that are placed on a Canvas. The zIndex value determines which UI element sits visually on top of another if both occupy the same place or overlap on the Canvas. The UI element with the larger zIndex value is displayed on top. The default zIndex value is zero (0) and all children are added at the upper-left corner of the Canvas. In the XAML code, the ZIndex is called an attached property, and is written as shown in the following example. In the previous example, the first button is smaller than the second one, and without a ZIndex it would be obscured. However, setting its ZIndex to a higher value than the second button means that it is displayed on top of the bigger button.

StackPanel UI Element Type The StackPanel is a layout manager that arranges child elements into a single line, which can be horizontal or vertical. The StackPanel is not a grid-based layout manager. Child elements are stacked vertically or horizontally as they are added to the StackPanel. UI elements move with the StackPanel parent but as a general rule are not resized if the parent is resized.

Note To get a UI element to always fill the width of the StackPanel, select that UI element, select the Stretch item in the HorizontalAlignment combo box, and then enter NaN in the Width text box in the Size and Position dialog.

XamlDevRef - 7.0.10


106

The order in which UI elements are displayed in the StackPanel is primarily determined by the order in which they are added, as shown in the following diagram (on the left) for which the corresponding XAML is displayed (on the right).

Although you can alter the position of a child UI element by manipulating the margins of a container to push the UI element outside of its natural flow, it is more common to reposition the control in relation to the other controls contained in the StackPanel. To change the order of a UI element in the Painting area, select the UI element and drag it to the required relative position in the stack. In the example in the following diagram, Button_3 has been selected and dragged out beyond the bottom of the last item in the stack in the previous diagram.

You can drop a UI element at any position within the stack. Controls in a StackPanel cannot overlap, however. Each control occupies a position in the stack relative to its neighboring controls.

Grid UI Element Type The Grid UI element is a grid-based layout manager. Within the Grid UI element, you can define a grid, which can be used resize the child elements automatically. The Grid has its own properties dialog, Grid Definition, which is displayed when the Grid has focus. By default, a grid has one row and column. It is at its most useful when it contains multiple rows and columns in which the resulting cells manage the position and size of the child controls.

XamlDevRef - 7.0.10


107

The left of the following diagram shows an example of the Grid Definition dialog in the Property area of the XAML Painter and at the right is an example of some Button controls and a GridSplitter positioned within the Painter area.

Key to the flexibility of the grid are the unit of measurement options that are available when defining width and height. These options are: Integer, where the value is defined in pixels Auto, where the size is determined by the size properties of the content object Asterisk (*), where the value is expressed as a weighted proportion of available space In the example in the previous diagram, the first column (that is, column 0) is 80 pixels wide, the third column (that is, column 2) is as wide as any content added to that column (in the previous example, a GridSplitter has been added), and the second and fourth columns divide the remaining space evenly between themselves. If the grid gets resized, the first column will remain 80 pixels wide, the column containing the grid splitter will remain the same size (as the grid splitter width has been fixed) and the remaining columns adjust their size accordingly. The previous diagram also shows the interaction between a grid and its child controls. By removing the height and width properties from the buttons, and the grid splitter, the grid becomes responsible for performing layout and sizing of the controls. You can also manipulate the grid properties by using the grid assistant. For details, see "Using the Grid Assistant", in the following subsection.

XamlDevRef - 7.0.10


108

The following Size and Position dialog settings were used for the buttons in the previous diagram. Button_1 has no defined width, deferring its width to be that of the first column. A defined height of 40 pixels and VerticalAlignment of Center positions the button with equal spacing top and bottom within the grid cell.

Button_2 has no defined width (like Button_1), but is a different size because it is set up to span two columns in the Grid.ColumnSpan text box. Although the first column (and therefore Button_1) has a fixed width, the width of the second column is proportional to the grid size. This means that the width of Button_2 changes accordingly if the grid resizes.

XamlDevRef - 7.0.10


109

Button_3 has no defined height. This would typically size the button to be not much taller than its content (that is, the caption). In this example, however, the VerticalAlignment text box has been set to Stretch, which causes the button to stretch to fill the available space.

Button_4 has a specified width and height. The HorizontalAligment and VerticleAlignment values mean that Button_4 is positioned in the middle of the grid cell.

XamlDevRef - 7.0.10


110

The GridSplitter has no defined height but has a defined width of 10 pixels. It has been placed into a column to which automatic sizing applies; that is, the width of the column is determined by the width of its children. The Grid.RowSpan property specifies that the GridSplitter should stretch over all rows in the grid and the VerticalAlignment value specifies that the splitter is to take all available vertical space.

Using the Grid Assistant When you maintain the Grid UI element type, you can use the grid assistant in the Painting area in addition to the Grid Definition dialog, to manipulate the columns and rows in the grid. To display the grid assistant 1.

In the Painting area, select the Grid UI element on your document. For details, see "Selecting a UI Element", in Chapter 3.

2.

Right-click and then select the Show Grid Assistant command from the popup menu that is displayed.

XamlDevRef - 7.0.10


111

The grid assistant is then displayed, as shown in the following diagram.

To hide the grid assistant, press ESC twice. Column and row properties are displayed across the top and down the left of the grid assistant, respectively. The width of each column, as recorded in the Grid Definition area, is displayed at the top of each column in the grid assistant. The height of each row, as recorded in the Grid Definition area, is displayed at the left of each row in the grid assistant. To adjust the width or height of a column or row, drag the blue triangle to the required position. (Your cursor becomes a double-headed arrow when you position it over a blue triangle.) The width or height of the adjacent column or row is adjusted accordingly and the values in the Grid Definition area are updated. When you select a column or row in the grid assistant, that column or row is highlighted with a red line and a tab indicates whether the width or height is: Determined automatically by the column or row contents; that is, A is highlighted in the tab Fixed; that is, 12 is highlighted in the tab Weighted proportion; that is, S is highlighted in the tab

XamlDevRef - 7.0.10


112

The following diagram shows an example of a column whose width is a weighted proportion.

Grid Assistant Popup Menu The grid assistant has a popup menu, unique to the grid assistant, that enables you to maintain rows and columns in the Grid UI element. The commands that are available depend on whether you select one or more rows or columns. The following table lists the commands that could be displayed when you right-click in the grid assistant. Command

Select this command to…

Insert New Column

Insert a new column. This action splits the current column at the position of your cursor.

Insert New Row

Insert a new row. This action splits the current row at the position of your cursor.

Insert New Column Splitter

Insert a column splitter at the left of the selected column. At run time, users can use the splitter to control the width of the column.

Insert New Row Splitter

Insert a row splitter at the top of the selected row. At run time, users can use the splitter to control the height of the row.

Delete Column

Delete the selected column or column splitter. You can delete one column at a time.

Delete Row

Delete the selected row or row splitter. You can delete one row at a time.

Make All Items AUTO

Set the width of all columns or rows in the grid to automatic; that is, the width or height is determined automatically by the column or row contents. If the column or row has no content, it collapses to zero width and is not visible in the Painting area.

Make Selected Items AUTO

Set the width of the selected items in a row or column to automatic; that is, the width or height is determined automatically by the column or row contents. If the column or row has no content, it collapses to zero width and is not visible in the Painting area.

Resize Items to Fill Selected Space

Resize the selected items so that they are evenly spaced.

XamlDevRef - 7.0.10


113

Command

Select this command to…

Resize Items to Primary Size

Resize the selected items to the same width or height as the primary selected row or column.

Using Resources in XAML Documents You can define Resource sections in your XAML documents. Resources can be used multiple times within a document and reusing them can help you to achieve a consistent look and feel throughout your application and may improve its performance over the Internet. Examples of resources include Styles, ControlTemplates, Brushes, or DataTemplates. A style is a collection of property setters that define property values, which differ from the default value for a Silverlight class. These styles, defined as resources, can be assigned to Silverlight components and all defined properties from the style are going to apply for the component. Styles are enclosed within the and tags, as shown in the following example.

The code in the previous example contains two styles. One style applies to all text boxes in the XAML document and another style that applies to all list boxes. Both of the styles in the previous examples make the UI elements appear in blue. A control template defines the appearance of a Silverlight control and how it changes its appearance if it changes its state. These control templates, defined as resources, can be assigned to Silverlight components and all defined properties from the template are going to apply for the component. Control templates are enclosed within the and tags.

XamlDevRef - 7.0.10


114

The following XAML code is an example of a control template that defines the look of ContentControl UI elements in a XAML document. This control template is used in every XAML document and does not define any animations for user interaction. It is responsible for the gray partially transparent frames that split the UI of every document into different parts.

For details about other Silverlight resources, see your Silverlight documentation. Additional details are available from the following URL. http://msdn.microsoft.com/en-us/library/cc838158(VS.95).aspx

Creating Controls Dynamically or from a Template The JADE XAML framework supports dynamic creation of objects of all new classes, except for the abstract classes mentioned under "Abstract Classes and Third-Party Controls", earlier in this chapter. Dynamic control creation can be used to create items for ItemsControl instances and to populate them. However, this can impact on your system performance for Silverlight stateful applications, as described in the following example. An item of an ItemsControl contains 10 visual elements and there are 15 different properties to set on each element by user logic. In Silverlight stateful applications, this results in 25 potential application server calls to the presentation client.

Note In Silverlight stateless applications, there is no traffic to and from the application server. There might be also 20 elements to add as child elements of this ItemsControl instance so there are 20 x 25 = 500 potential calls from the application server to the presentation client. The application performs well using a local area network but not well using the Internet. displayAllPeople(personCollection: PersonArray); vars person: Person; image: XamlImage; panel: XamlStackPanel; textBlock: XamlTextBlock; begin foreach person in PersonArray do create image; create panel; create textBlock; textBlock.text := person.name.StringUTF8;

XamlDevRef - 7.0.10


115

image.setSource(person.photo); panel.children.add(image); panel.children.add(textBlock); myListBox.addItem(panel); endforeach; end; The solution for this specific problem is to use templates to create the items. An ItemsControl template is a piece of XAML that is attached to the control and defines how each item is to look at run time. The visual components used to create an item are likely to be identical for each item and they are populated with a different set of data. A template, defined in the document XAML of the control, can contain the description of how an item looks and also contains the data binding for each item. For example, it might contain a TextBlock where the text property is bound to a JADE property of a data item. These data items are instances of JADE classes and contain public primitive properties. All of these properties can be bound against properties of elements that are used inside the template. XAML: The itemsSource property of the ItemsControl class is used to send an assigned collection of data items to the presentation client. The data items are serialized and the bound property values are displayed. An example of using the itemsSource property is shown in the following code. displayAllPeople(personCollection: PersonArray); begin