summaryrefslogtreecommitdiff
path: root/pages
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2018-08-28 07:18:46 -0700
committerapache <apache@e5-web1.enlightenment.org>2018-08-28 07:18:46 -0700
commit1d1e262a7cd067ddae6e30739437fde4a5ae3a2b (patch)
treec8f79cec9d5d6d17ee1ed04da155a3537c4ed884 /pages
parent961f0c4ab558a001ea5f53fc6b1c1c1d843d27c6 (diff)
Wiki page hello-world-gui-cs.md changed with summary [created] by Xavi Artigas
Diffstat (limited to 'pages')
-rw-r--r--pages/develop/tutorials/csharp/hello-world-gui-cs.md.txt258
1 files changed, 258 insertions, 0 deletions
diff --git a/pages/develop/tutorials/csharp/hello-world-gui-cs.md.txt b/pages/develop/tutorials/csharp/hello-world-gui-cs.md.txt
new file mode 100644
index 000000000..65214df47
--- /dev/null
+++ b/pages/develop/tutorials/csharp/hello-world-gui-cs.md.txt
@@ -0,0 +1,258 @@
1---
2~~Title: Graphical "Hello World" in C#~~
3~~NOCACHE~~
4---
5
6# Graphical "Hello World" in C# #
7
8In this guide you will learn how to build a complete graphical application, with a window and typical elements like a text box and a button.
9
10| | WARNING | |
11| --- | ------- | --- |
12| ![NOTE](/_media/note-important.png) | **The C# bindings are currently in BETA state**<br>They should only be used for experimenting and **NOT** for any product development.<br>The source code for the tutorials is subject to change in the future. | ![NOTE](/_media/note-important.png) |
13
14## Prerequisites ##
15
16* Read the [Setting Up a C# Development Environment](/develop/setup/csharp/) guide so you are able to build and run EFL C# applications.
17* This tutorial builds on top of the previous one, ["Hello World" in C#](hello-world-cs.md), so you should have read that one first.
18
19## Graphical Hello World ##
20
21Copy the code below into a file and build as instructed in the [Setting Up a C# Development Environment](/develop/setup/csharp/) guide.
22
23```csharp
24using System;
25
26public class Example
27{
28 // Callback to quit the application
29 public static void QuitCb(object sender, EventArgs e)
30 {
31 // Exit the EFL main loop
32 efl.ui.Config.Exit();
33 }
34
35#if WIN32
36 [STAThreadAttribute()]
37#endif
38 public static void Main()
39 {
40 // Initialize EFL and all UI components
41 efl.All.Init(efl.Components.Ui);
42
43 // Create a window and initialize it
44 efl.ui.IWin win = new efl.ui.Win(efl.App.GetLoopMain(), (efl.ui.IWin ewin) => {
45 // Set the window's title
46 ewin.SetText("Hello World");
47 // Request that the window is automatically hidden when the "close"
48 // button is pressed
49 ewin.SetAutohide(true);
50 // Hook to the Hide event
51 ewin.HideEvt += QuitCb;
52 });
53
54 // Create a box container
55 efl.ui.IBox box = new efl.ui.Box(win, (efl.ui.IBox ebox) => {
56 // Set its minimum size
57 ebox.SetHintMin(new eina.Size2D(360, 240));
58 // Set the box as the content for the window
59 // The window size will adapt to the box size
60 win.SetContent(ebox);
61 });
62
63 // Create a text label widget
64 new efl.ui.Text(box, (efl.ui.IText etext) => {
65 // Set its content and customize it
66 etext.SetText("Hello World. This is an Efl.Ui application!");
67 etext.SetSelectionAllowed(false);
68 etext.SetHintWeight(1.0, 0.9);
69 etext.SetHintAlign(0.5, 0.5);
70 // Add the text to the box container
71 box.DoPack(etext);
72 });
73
74 // Create a button widget
75 new efl.ui.Button(box, (efl.ui.IButton ebutton) => {
76 // Customize it
77 ebutton.SetText("Quit");
78 ebutton.SetHintWeight(1.0, 0.1);
79 // Set the method to be called when the button is pressed
80 ebutton.ClickedEvt += QuitCb;
81 // Add the button to the box container
82 box.DoPack(ebutton);
83 });
84
85 // Start the EFL main loop
86 efl.ui.Config.Run();
87
88 // Shutdown EFL
89 efl.All.Shutdown();
90 }
91}
92```
93
94When you run the application, it should look something like this:
95
96![Full application with text box and button](/_media/playground/03-hello-world-gui/image01.png)
97
98## Walkthrough ##
99
100This tutorial builds on top of the previous one, ["Hello World" in C#](hello-world-cs.md), so the basic structure, including EFL initialization and shutdown, are the same. The following steps explain how to further customize the window and add the different widgets to it.
101
102### Registering for Window Events ###
103
104Take a look at the window instantiation:
105
106```csharp
107 // Create a window and initialize it
108 efl.ui.IWin win = new efl.ui.Win(efl.App.GetLoopMain(), (efl.ui.IWin ewin) => {
109 // Set the window's title
110 ewin.SetText("Hello World");
111 // Request that the window is automatically hidden when the "close"
112 // button is pressed
113 ewin.SetAutohide(true);
114 // Hook to the Hide event
115 ewin.HideEvt += QuitCb;
116 });
117```
118
119This creates a new window, making it a child of the application's Main Loop, and customizing it with an initialization method. In this case, the initialization method is a lambda function which:
120
121* Sets the window title to `Hello World`.
122* Sets the `autohide` flag to `true` (see the [previous tutorial](hello-world-cs.md)).
123* Connects an event handler to the window's `Hide Event`. This event will be emitted whenever the window is closed, because of the `autohide` flag above.
124
125All event handlers in EFL have the same signature:
126
127```csharp
128 public static void Handler(object sender, EventArgs e);
129```
130
131Where `sender` is the object that emitted the event, and `e` contains any additional information, which depends on the type of the event.
132
133> **NOTE:**
134> `e` must be cast to the correct type to be able to extract this information. For example, when connecting to the `efl.input.Interface.KeyDownEvt` to be informed of key presses, you must cast `e` to `efl.input.Interface.KeyDownEvt_Args` to retrieve the actual key.
135
136This tutorial simply quits the application whenever the window is closed:
137
138```csharp
139 // Callback to quit the application
140 public static void QuitCb(object sender, EventArgs e)
141 {
142 // Exit the EFL main loop
143 efl.ui.Config.Exit();
144 }
145```
146
147This is already the default behavior for EFL applications, so this event is connected here just for demonstration purposes.
148
149### Adding a Container Box ###
150
151Now you could start adding widgets directly to your window, but you would need to manually give them a position and a size. If later on you decide to make your window bigger, or if you want your window to be resizable by the user, you'll need to change the position and size of every widget.
152
153It is easier to put your widgets inside a *container* which takes care of positioning and sizing them, according to available space and other widgets. There's a variety of containers available, which allow you to stack your widgets vertically or horizontally, or align them on a square grid, for example.
154
155Although invisible themselves, containers are regular widgets too, so you can size and position them, and even nest them under other containers.
156
157This tutorial uses a *box* container:
158
159```csharp
160 // Create a box container
161 efl.ui.IBox box = new efl.ui.Box(win, (efl.ui.IBox ebox) => {
162 // Set its minimum size
163 ebox.SetHintMin(new eina.Size2D(360, 240));
164 // Set the box as the content for the window
165 // The window size will adapt to the box size
166 win.SetContent(ebox);
167 });
168```
169
170A box container can be vertical or horizontal, and by default it is vertical. All widgets inside a vertical box container will have the same width as the container, and their heights will be automatically chosen so that they cover the whole surface of the container from top to bottom (Imagine a stack of pizza boxes neatly fitting inside your oven). By default, all widgets will have the same height, but that can be customized as you will see in a moment.
171
172In the initialization method of the box above you can see calls to:
173
174* `SetHintMin()`: This sets the **minimum** size for the box. You can resize the window and the box will grow or shrink as needed, but it will never go below this size.
175
176* `SetContent()`: This method specifies the **one** widget which will be the content of the window (Windows can only have one content set at any given time). If you want to have more than one widget in your window, you will need to wrap them in a container and set that as the content of the window. As shown above, the box container is set as the content of the window.
177
178### Adding a Text Label ###
179
180So far the tutorial has created a window and an invisible container, it is about time it adds something which can actually be seen:
181
182```csharp
183 // Create a text label widget
184 new efl.ui.Text(box, (efl.ui.IText etext) => {
185 // Set its content and customize it
186 etext.SetText("Hello World. This is an Efl.Ui application!");
187 etext.SetSelectionAllowed(false);
188 etext.SetHintWeight(1.0, 0.9);
189 etext.SetHintAlign(0.5, 0.5);
190 // Add the text to the box container
191 box.DoPack(etext);
192 });
193```
194
195This instantiates an `efl.ui.Text` object, as a child of the box container. Quite sensibly, this is the widget used to display text on screen. The initialization above is worth a careful look:
196
197* `SetText()`: Specifies the text string to display in the widget.
198* `SetSelectionAllowed()`: This disables selecting the text (by dragging over it with the mouse, for example). Just to showcase a bit the EFL's capabilities.
199* `SetHintWeight()`: This one controls the widget's size, but, instead of setting it explicitly as `SetHintMin()` did, it does so indirectly by giving the widget a **weight**. The container holding this widget decides the size for all its held widgets according to their relative weights (If all widgets have the same weight, they all have the same size. If you double the weight of one of the widgets, its size will be double that of the other widgets). This is a complex topic explained in its own tutorial (coming soon).
200
201 In the code above, the text widget is given a weight of `1.0` in the horizontal direction and `0.9` in the vertical direction (both directions are treated separately). The effect of this on the final widget size depends on the other widgets' weights, so it is explained in the next section.
202
203* `SetHintAlign()`: Once the container has allocated space for each widget according to its weight, if the actual widget is smaller, it has room to be aligned. This command controls horizontal and vertical alignment in this way: `0` means left (or top), `1` means right (or bottom), and intermediate values are possible, meaning intermediate positions. For example, `0.5` means centered, as used in the code.
204
205 > **NOTE**:
206 > There is currently an issue in EFL preventing correct vertical alignment of widgets inside vertical boxes (and horizontal alignment inside horizontal boxes). You can follow the resolution progress in ticket [T7352](https://phab.enlightenment.org/T7352).
207
208* `Efl.ui.Box.DoPack()`: This adds the text widget to the box container. The order in which widgets are added to a container dictates the order in which they are placed on the screen.
209
210 Besides being a child of the box object, the text widget also needs to be *packed* into the box with `DoPack()`.
211
212It is worth noting that, as hinted in the [previous tutorial](hello-world-cs.md), no variable is needed to store the widget: after its construction, it is already fully initialized (customized) and a reference has been handled to a parent which will take care of its destruction. This results in a very compact way to build user interfaces!
213
214### Adding a Button ###
215
216Let's now add a button below the text label:
217
218```csharp
219 // Create a button widget
220 new efl.ui.Button(box, (efl.ui.IButton ebutton) => {
221 // Customize it
222 ebutton.SetText("Quit");
223 ebutton.SetHintWeight(1.0, 0.1);
224 // Set the method to be called when the button is pressed
225 ebutton.ClickedEvt += QuitCb;
226 // Add the button to the box container
227 box.DoPack(ebutton);
228 });
229```
230
231This instantiates a button as a child of the box and initializes it so:
232
233* Its label is set to `Quit`.
234* Its vertical weight is set to `0.1`. The only other widget inside the box container is the text label created in the previous section, with a weight of `0.9`, so these two widgets will share the total height of the window at a 90% - 10% ratio.
235
236 > **NOTE**: You could also use `1` and `9` for the weights, or `10` and `90`, to achieve the same results. Remember that the weights are relative.
237
238* It connects the `QuitCb()` event handler to the `Clicked` event. In this way, when the button is pressed, the application will exit.
239* Adds the button to the box (besides being a child of the box object, the button also needs to be *packed* into the box with `DoPack()`).
240
241## Summary ##
242
243At the end of this tutorial you have learned:
244
245* How to react to **events** like window a being closed or a button being clicked.
246* How to use **container** widgets to take care of other widget's position and size.
247* How to further customize a widget's position and size using **weight** and **alignment** hints.
248
249## Further Reading ##
250
251[Setting up a C# Development Environment](/develop/setup/csharp/)
252: Read this before trying to develop with the EFL and C#
253
254["Hello World" in C#](hello-world-cs.md)
255: First tutorial in the series, explaining the basics.
256
257[Tutorial Code Examples](https://git.enlightenment.org/tools/examples.git/tree/tutorial/csharp)
258: C# Source code for the tutorials.