← Back to branch summary

~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

« back to all changes in this revision

Viewing changes to external/xwt/README.markdown

  • Committer: Package Import Robot
  • Author(s): Jo Shields
  • Date: 2013-05-12 09:46:03 UTC
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20130512094603-mad323bzcxvmcam0
Tags: upstream-4.0.5+dfsg
Import upstream version 4.0.5+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
external/xwt/README.markdown
 
1
This document is an introduction to XWT, a cross-platform UI toolkit
 
2
for creating desktop applications.
 
3
 
 
4
If you have any question about XWT or do you want to contribute
 
5
a discussion group for XWT is available here:
 
6
 
 
7
http://groups.google.com/group/xwt-list
 
8
 
 
9
Introduction
 
10
============
 
11
 
 
12
Xwt is a new .NET framework for creating desktop applications that run
 
13
on multiple platforms from the same codebase.   Xwt works by exposing
 
14
one unified API across all environments that is mapped to a set of
 
15
native controls on each platform.
 
16
 
 
17
This means that Xwt tends to focus on providing controls that will
 
18
work across all platforms. However, that doesn't mean that the
 
19
functionality available is a common denominator of all platforms.
 
20
If a specific feature or widget is not available in the
 
21
native framework of a platform, it will be emulated or implemented
 
22
as a set of native widgets.
 
23
 
 
24
Xwt can be used as a standalone framework to power the entire application
 
25
or it can be embedded into an existing host.  This allows developers
 
26
to develop their "shell" using native components (for example a Ribbon
 
27
on Windows, toolbars on Linux) and use Xwt for specific bits of the
 
28
application, like dialog boxes or cross platform surfaces. 
 
29
 
 
30
Xwt works by creating an engine at runtime that will map to the
 
31
underlying platform.   These are the engines that are supported on
 
32
each platform:
 
33
 
 
34
* Windows: WPF engine, Gtk engine (using Gtk#)
 
35
* MacOS X: Cocoa engine (using MonoMac) and Gtk engine (using Gtk#)
 
36
* Linux: Gtk engine (using Gtk#)
 
37
 
 
38
This means for example that you can write code for Xwt on Windows that
 
39
can be hosted on an existing WPF application (like Visual Studio) or
 
40
an existing Gtk# application (like MonoDevelop).   Or on Mac, you can
 
41
host Xwt on an existing Cocoa/MonoMac application or you can host it
 
42
in our own MonoDevelop IDE.
 
43
 
 
44
Getting Started
 
45
---------------
 
46
 
 
47
Open the Xwt.sln with MonoDevelop (or VisualStudio on Windows) and
 
48
build the solution.   You should end up with the libraries that you
 
49
can use in your project and a couple of sample applications.
 
50
 
 
51
Using Xwt in your app
 
52
---------------------
 
53
 
 
54
Based on your platform and the backend that you want to use, you need
 
55
to pick the libraries that you want to use in your project.
 
56
 
 
57
* Windows+WPF: Xwt.dll + Xwt.WPF.dll (requires WPF)
 
58
* Windows+Gtk: Xwt.dll + Xwt.Gtk.dll (requires Gtk#)
 
59
* Linux+Gtk: Xwt.dll + Xwt.Gtk.dll (requires Gtk#)
 
60
* Mac+Gtk: Xwt.dll + Xwt.Gtk.dll (requires Gtk#)
 
61
* Mac+Cocoa: Xwt.dll + Xwt.Mac.dll (requires MonoMac.dll)
 
62
 
 
63
Hello World
 
64
-----------
 
65
 
 
66
To write your first application, create an empty .NET project in your
 
67
favorite language in MonoDevelop or Visual Studio and reference the
 
68
Xwt.dll library. This is the only library that you need to reference
 
69
at compile time.
 
70
 
 
71
This is the simplest Xwt program you can write:
 
72
 
 
73
        using System;
 
74
        using Xwt;
 
75
        
 
76
        class XwtDemo {
 
77
                [STAThread]
 
78
                static void Main ()
 
79
                {
 
80
                        Application.Initialize (ToolkitType.Gtk);
 
81
                        var mainWindow = new Window (){
 
82
                                Title = "Xwt Demo Application",
 
83
                                Width = 500,
 
84
                                Height = 400
 
85
                        };
 
86
                        mainWindow.Show ();
 
87
                        Application.Run ();
 
88
                        mainWindow.Dispose ();
 
89
                }
 
90
        }
 
91
 
 
92
You use the Application.Initialize() method to get the backend
 
93
initialized. In this example we are using the Gtk backend. If you
 
94
want to use another backend, just change the parameter provided
 
95
to the Initialize() method. Also make sure the appropiate backend
 
96
DLL is available in the application directory.
 
97
 
 
98
Then we create an instance of the Window class, this class exposes two
 
99
interesting properties, MainMenu which can be used to set the Window's
 
100
main menu and "Content" which is of type "Widget" and allows you to
 
101
add some content to the window.
 
102
 
 
103
Finally, the Application.Run method is called to get the UI events
 
104
processing going.
 
105
 
 
106
Widget Class Hierarchy
 
107
======================
 
108
 
 
109
You will be using widgets to create the contents for your
 
110
application.   Xwt.Widget is the abstract base class from which all
 
111
the other components are created.  
 
112
 
 
113
Some Widgets can contain other widgets, these are container widgets,
 
114
and in Xwt those are Canvas, Paned, HBox, VBox and Table.  The first
 
115
two implement a box layout system, while the last one implements a
 
116
Table layout that allows widgets to be attached to different
 
117
anchor-points in a grid.
 
118
 
 
119
The layout system uses an auto-sizing system similar to what is
 
120
availble in Gtk and HTML allowing the user interface to grow or shrink
 
121
based on the contents of the childrens on it.
 
122
 
 
123
* XwtComponent 
 
124
    * Menu
 
125
    * MenuItem
 
126
    * Widget
 
127
        * Box (Container)
 
128
            * HBox (Container)
 
129
            * VBox (Container)
 
130
        * Button
 
131
            * MenuButton
 
132
            * ToggleButton
 
133
        * Canvas (Container)
 
134
        * Checkbox
 
135
        * ComboBox
 
136
        * Frame
 
137
        * ImageView
 
138
        * Label
 
139
        * ListView
 
140
        * NoteBook
 
141
        * Paned (Container)
 
142
            * HPaned (Container)
 
143
            * VPaned (Container)
 
144
        * ProgressBar
 
145
        * ScrollView
 
146
        * Separator
 
147
            * VSeparator
 
148
            * HSeparator
 
149
        * Table (Container)
 
150
        * TextEntry
 
151
        * TreeView
 
152
    * WindowFrame
 
153
        * Window
 
154
            * Dialog
 
155
 
 
156
For example, the following attaches various labels and data entries to
 
157
a Table:
 
158
 
 
159
        t = new Table ();
 
160
        t.Attach (new Label ("One:"), 0, 1, 0, 1);
 
161
        t.Attach (new TextEntry (), 1, 2, 0, 1);
 
162
        t.Attach (new Label ("Two:"), 0, 1, 1, 2);
 
163
        t.Attach (new TextEntry (), 1, 2, 1, 2);
 
164
        t.Attach (new Label ("Three:"), 0, 1, 2, 3);
 
165
        t.Attach (new TextEntry (), 1, 2, 2, 3);
 
166
 
 
167
 
 
168
The Application Class
 
169
=====================
 
170
 
 
171
The Application class is a static class that provides services to run
 
172
your application.  
 
173
 
 
174
Initialization 
 
175
--------------
 
176
 
 
177
The Application.Initialize API will instruct Xwt to initialize its
 
178
binding to the native toolkit. You can pass an optional parameter to
 
179
this method that specifies the full type name to load as the backend.
 
180
 
 
181
For example, you can force the initialization of the backend to be
 
182
specifically Gtk+ or specifically MonoMac based on MacOS.   This is
 
183
currently done like this:
 
184
 
 
185
        Application.Initialize ("Xwt.GtkBackend.GtkEngine, Xwt.Gtk, Version=1.0.0.0");
 
186
 
 
187
or:
 
188
 
 
189
        Application.Initialize ("Xwt.Mac.MacEngine, Xwt.Mac, Version=1.0.0.0");
 
190
 
 
191
As you saw from the Hello World sample, toplevel windows are created
 
192
by creating an instance of the "Xwt.Window" class.   This class
 
193
exposes a couple of properties that you can use to spice it up.   The
 
194
MainMenu property is used to control the contents of the application
 
195
menus while the "Content" property is used to hold a Widget.
 
196
 
 
197
Timers
 
198
------
 
199
 
 
200
The Application.TimeoutInvoke method takes a timespan and a Func<bool>
 
201
action method and invokes that method in the main user interface
 
202
loop.  
 
203
 
 
204
If the provided function returns true, then the timer is restarted,
 
205
otherwise the timer ends.
 
206
 
 
207
Background Threads
 
208
------------------
 
209
 
 
210
It is very common to perform tasks in the background and for those
 
211
tasks in the background to later update the user interface.   The Xwt
 
212
API is not thread safe, which means that calls to the Xwt API must
 
213
only be done from the main user interface thread.
 
214
 
 
215
This is a trait from the underlying toolkits used by Xwt.
 
216
 
 
217
If you want a background thread to run some code on the main loop, you
 
218
use the Application.Invoke (Action action) method.   The provided
 
219
"action" method is guaranteed to run on the main loop.
 
220