Drawing surfaces, objects, and widgets

by Gabriele del Giovine, translated by Julie Hirt

3.1 Drawing surfaces and objects that can be created in a Wisej.NET application

Wisej.NET provides a wide range of components suitable for implementing various typical use cases in Line of Business (LOB) application development. Many of these components also offer a design surface that allows for the visual creation of application UIs. Below is a list of the available built-in components:

You can see this screen by right-clicking in the Solution Explorer and selecting Add -> New Item

The ones that interest us at the moment are those that offer a drawing surface that allows for easy creation of a UI (user interface) in a visual way.

3.1.1 Why it's important to have a drawing surface

This feature is not always present in web development tools, due to their dynamic nature and the need for responsive adaptation of the UI to the type of device/browser used. The dynamism required at runtime would make development unnecessarily burdensome and imprecise through a visual drawing surface.

It should be remembered that Wisej.NET is a tool for developing LOB (Line of Business) applications, applications that by their nature must have precise, consistent UIs that are inherently suited to being designed with precision and ergonomics. It is worth considering that often the time spent by analysts and developers studying and implementing the UI of an LOB application is far greater than the time spent managing the underlying business logic. This means that the use of development tools without a visual drawing surface presents a major obstacle to productivity and manageability of the application over time.

3.2 Elements with available drawing surfaces

The elements with a drawing surface follow the types of applications available in Wisej.NET and behave in the same way with some small differences. Below is the list of elements with a drawing surface.

Object Type	Reference Application Type	Project File Name
	Web Page Application	Page
	Web Application	Window
	Web Desktop Application	Desktop
	All	UserControl

3.2.1 The files that contain the code managed by the drawing surface

Wisej.NET is fully integrated into Microsoft Visual Studio and follows its standards for managing the files that make up the various components of a solution. In the case of the designer, we have the main .cs or .vb file (for example, Page1.cs) and the related designer files (Page1.Designer.cs) and resource files (Page1.resx).

The designer's code management will automatically create and maintain the code present within the designer file (ie Page1.Designer.cs). It is possible to customize this code manually if deemed necessary. If there are errors in the designer file, it cannot be opened in design view until the errors are fixed.

3.3 The drawing surface toolbar

An important element of the designer is the toolbar. It contains functionalities aimed at facilitating interaction with the designer itself and with the objects contained within it.

The toolbar

Toolbar Icon	Description
	Shows a welcome page with links to resources, help, and tips
	Cycle through the various usable themes in the drawing surface
	Change the color used for selection lines and various glyphs.
	Change the resolution of the drawing surface selection-alignment grid.
	Change the client profile shown in design view. By changing the client profile, the property values related to the responsiveness of various objects are updated.
	Create a screenshot of the selected control or the entire drawing surface and save it to the clipboard.
	Show or hide controls with the "Visible" property set to false. The designer normally shows all controls present on the drawing surface. When there are multiple controls that overlap or can be hidden or shown at runtime, the view can become too complex or confusing. Using this functionality helps mitigate the problem.
	Update the selected controls or the entire drawing surface. This is useful when the rendering of a control is incomplete due to the complexity of the object or errors in the objects themselves.
	Show or hide anchor glyphs. These are used to "anchor" a specific side of a control to it's parent, which keeps the relative distance the same as the parent is resized.
	Show the Wisej.NET controls toolbox. The toolbox is where you can select Wisej.NET controls to add to the designer.
	Show the object hierarchy structure (document outline)
	Set the tab order of objects on the drawing surface. Select "Manual" in order to create the tab order yourself by clicking on each object in order. Select "Horizontal" to set the tab order to go from left to right horizontally. Select "Vertical" to set the tab order to go from top to bottom vertically.
	Show the automatic layout generation tool for the selected controls on the drawing surface. This allows you to quickly arrange controls in different layouts- ie ordered horizontally, ordered vertically, docked to the left.
	Show the properties window of the selected control/object. This window can also be shown by selecting View -> Properties Window or by pressing F4.
	Shows the name, position and dimensions of the selected control/object.
	Opens a window which contains options to configure the HTML rendering method and to "recycle" the designer, which is useful when a control is not loading.
	Show the Wisej.NET license panel.

3.4 Creating and interacting with controls/objects.

Both the visual and non-visual approaches can be used to create and position a control on the drawing surface. In the visual approach, the Wisej.NET toolbox is opened, the object is dragged onto the drawing surface and positioned where desired, and the properties/events management window is used to manage the properties and events of the selected control. It is the designer's and Visual Studio IDE's task to generate the various code parts in the files that make up the Page, Window, etc. container. Alternatively, it is possible to create all controls by manually writing the relevant code. The manual approach is useful when controls need to be created dynamically. In all other cases, it is better to use the visual method.

3.4.1 The visual approach to creating/interacting with controls.

After creating a template (in this example a Web Page Application), and double clicking on the designer file (in this example Page1.cs) we will have the following situation in Visual Studio:

Select the Wisej.NET toolbox icon by clicking on it in the toolbar, or by selecting View -> Toolbox. The controls/objects toolbox for Wisej.NET will be displayed like so:

Now we will add two controls to the design surface, a "TextBox" and a "Button". Simply perform a Drag & Drop operation. The goal of the application is to invite the user to write their name and, after pressing the button button1, display a message box on the page with the text "Hello world! My name is" followed by the name entered by the user.

The newly created textbox and button

By clicking either object to select it, you can see the snap points for anchoring, movement and resizing, as well a box with an arrow in the upper-right corner, which opens a menu for quickly editing the main properties.

You can open the document outline by clicking on the corresponding button from the toolbar. Notice that two objects have been inserted, one named "textBox1" and one named "button1".

Toolbar button that opens the document outline

The document outline. In this case, Page1 contains the objects button1 and textBox1

Select "button1" by clicking on the control or selecting "button1" in the document outline. This will show its properties window. Change the value of the Text property to "Hello World!".

button1 is selected in the document outline

The button1 Properties window. Here we have changed the text to "Hello World!"

Select "textbox1" and open its properties window. Find the "Label" property and click on the "+" by it. Modify the "Label.Text" property to be "My name is". Note that this is different from the Text property- the Text property controls the text inside of the textbox, whereas the Label.Text property controls the text right outside of the textbox.

In the designer now we will have this situation:

The textbox Label.Text property is set to "My name is". The button Text property is set to "Hello World!

We can align the button "button1" better by selecting it and positioning it where we want or by modifying the "Location" property. As you will notice, the object model follows that of Windows Forms TextBox and Button controls.

3.4.2 Code generated by the designer

Now let's see what the designer has generated in the Page1.cs, Page1.Designer.cs, and Page1.resx files. Essentially, a Page1 class was generated in the "WisejWebApplication" namespace, which derives from the base class Wisej.Web.Page with a partial class declaration (distributed over multiple source files). The code of the Page1 class is contained in the Page1.cs and the Page1.Designer.cs files.

The Page1 class as seen in the Visual Studio Solution Explorer

Note that the code from the Page1.cs and Page1.Designer.cs files could have easily been written manually. It is not advised to manually edit the Page1.resx file.

The Page1.cs File

using Wisej.Web;

namespace WisejWebPageApplication1
{
	public partial class Page1 : Page
	{
		public Page1()
		{
			InitializeComponent();
		}
	}
}

The Page1.cs file contains the declaration of the Page1 class. Inside the Page1 class, there is the constructor method Page1() which invokes the component initialization method, InitializeComponent(). InitializeComponent()is defined in the Page1.Designer.cs file:

The Page1.Designer.cs File

namespace WisejWebPageApplication1
{
	partial class Page1
	{
		/// <summary>
		/// Required designer variable.
		/// </summary>
		private System.ComponentModel.IContainer components = null;

		/// <summary>
		/// Clean up any resources being used.
		/// </summary>
		/// <param name="disposing">true if managed resources should be disposed; otherwise, false.</param>
		protected override void Dispose(bool disposing)
		{
			if (disposing && (components != null))
			{
				components.Dispose();
			}
			base.Dispose(disposing);
		}

		#region Wisej Designer generated code

		/// <summary>
		/// Required method for Designer support - do not modify
		/// the contents of this method with the code editor.
		/// </summary>
		private void InitializeComponent()
		{
			this.textBox1 = new Wisej.Web.TextBox();
			this.button1 = new Wisej.Web.Button();
			this.SuspendLayout();
			// 
			// textBox1
			// 
			this.textBox1.LabelText = "My name is";
			this.textBox1.Location = new System.Drawing.Point(85, 58);
			this.textBox1.Name = "textBox1";
			this.textBox1.Size = new System.Drawing.Size(93, 53);
			this.textBox1.TabIndex = 0;
			// 
			// button1
			// 
			this.button1.Location = new System.Drawing.Point(195, 51);
			this.button1.Name = "button1";
			this.button1.Size = new System.Drawing.Size(100, 37);
			this.button1.TabIndex = 1;
			this.button1.Text = "Hello World!";
			// 
			// Page1
			// 
			this.AutoScaleDimensions = new System.Drawing.SizeF(7F, 19F);
			this.AutoScaleMode = Wisej.Web.AutoScaleMode.Font;
			this.Controls.Add(this.button1);
			this.Controls.Add(this.textBox1);
			this.Name = "Page1";
			this.Size = new System.Drawing.Size(980, 761);
			this.ResumeLayout(false);
			this.PerformLayout();

		}

		#endregion

		private Wisej.Web.TextBox textBox1;
		private Wisej.Web.Button button1;
	}
}

Page1.Designer.cs contains the definition of InitializeComponent(). Inside the InitializeComponent() method, we find the declaration and creation of all objects (textbox1 and button1) and the setting of their properties (ie, Name and Size). In addition, we find the Dispose() destructor method.

The Page1.resx File

The Page1.resx file is an embedded resource. It can contain multiple resources such as strings and binary data. In this case, the Page1.resx file contains a single item called $this.RulerSnapLines. $this.RulerSnapLines is a set of helper lines you can define in Visual Studio to help with positioning. When dragging objects across the designer, they will snap to these lines. You can click on the ruler to add new lines or on an existing line to remove it.

An example of a ruler snap line.

3.5 Event Management

Now that we have positioned our UI elements on the page, we need to manage our use case (the message box with the text "Hello world! My name is"). To do this, we need to handle the click event of button1, and verify that the user enters a value other than nothing or just empty spaces. So, we select the button1 object and its property window, making sure to click on the EVENT filter button (as shown here)

The property window of the button. An arrow points to the EVENT filter button.

Double clicking on the Click event will generate the corresponding handler.

The window tells us that the button1_Click method has been associated with the Click event of button1. Double-clicking on the event allows us to go directly to the generated code in Page1.cs. Let's observe what has been generated in the Page1.cs file:

The Page1.cs file now contains a button1_Click() function

Let's also observe what has been generated in the Page1.Designer.cs file inside the InitializeComponent() method:

this.button1.Click += new System.EventHandler(this.button1_Click);

As you can see, the button1_Click method is defined in the Page1.cs file. button1_Click is attached as a handler of the Click event (using the += operator) in the Page1.Designer.cs file. All of this code could have been written manually instead.

3.5.1 The button1_Click method code

Let's now move on to handling the required use case, which is the issuance of a message (specifically, an AlertBox in the browser) following the press of the button1 button, after checking that the user has entered a value in the textbox1 textbox that is different from null or a string composed only of spaces.

private void button1_Click(object sender, System.EventArgs e)
{
	string userName = this.textBox1.Text;
	if (userName == null || userName.Trim() == "")
	{
		AlertBox.Show("Tell me your name!");
	} else
	{
		AlertBox.Show("Hello world, my name is "+userName);
	}
}

The button1_Click() code

The application when the textbox is blank

The application when a string is typed in the textbox

As you can see, only C# has been used, executed server-side, and there is no JavaScript in the sources, no HTML file other than the default one, no .js file, no .css file, or other files with other markup languages. There are no complex initializations/builders/constructors or page routing mechanisms or code that handles application/page state.

A Wisej.NET session contains the entire state of the application. The state contains all the objects created by the app, including all visual components. Unfortunately, the session is lost if the server goes offline. This issue can be mitigated by storing data outside of the session (ie on disk, shared storage, database, via a tool such as Redis) so that if a session crashes due to the server going offline, in-progress work can be recovered.