User talk:Akaya

Introduction to Frameworks: Geyser and Vyzor

Frameworks can make GUI creation loads easier by providing support for common GUI-related goals. The two most commonly used in the Mudlet world are Geyser and Vyzor. Each have their own pros and cons and it is ultimately up to you as to which you choose. Vyzor is great for creating an entire GUI and sharing them with others as it handles window resizing for you. Meaning the GUI will appear the same regardless of the user's screen size. Geyser handles widgets much better than Vyzor but does not offer dynamic resizing or individual manipulation of stylesheet elements by default. In short, there is really nothing that one can do that the other cannot with a bit of work. Again, the decision is up to you.

Geyser

One of the major highlights of Geyser is that it is built into Mudlet. No installation is necessary to utilize its API. This makes sharing your work a breeze.

Create a label

Click to enlarge

<lua>myLabel = Geyser.Label:new({

 name = "myLabel",
 x = 0,
 y = "50%",
 width = 100,
 height = "10%",

},main)</lua>

1. Geyser.Label:new() To create a label via Geyser we must use the Geyser.Label:new() function. It has two parameters: a table of label information and the container.
2. Setting a variable Though not necessary, it is normally a wise choice to assign our label to a variable. This will allow us to refer to it later on. In our example, the variable name is set to myLabel.
3. Name This is the name that Geyser will use internally to manipulate our label. It is not uncommon (and usually best) to have this match our variable name. We've done this in our example, naming it myLabel
4. Position This is where our label will reside on the screen in relavance to the main Mudlet window via x and y coordinates. 0,0 representing the top left. These coordinates can be a percentage of its container encased in quotations (a string) or a pixel value (a number). In our example, x is set to 0 (a pixel value) which will hug it to the left side of the screen. y is set to "50%" which will set it halfway down the screen. If we want to adjust the starting position of the label, we would adjust these values.
5. Size This will determine the size of our label using width and height. Just like the position, this can be a percentage or pixel value. In our example, the width has been set to 100 which will make it 100px wide. The height is set to "10%" which will make it's height 10% of the main Mudlet window.
6. Container The container is the last thing to be specified during label creation. It is the second parameter of Geyser.Label:new() so you'll want to separate it from the first with a comma as shown in the above example. Since we don't really have a container made yet, we're simply placing the label in the main Mudlet window or main.

Style a label

Click to enlarge

<lua>myLabel:setStyleSheet([[

 background-color: blue;

]])</lua>

1. setStyleSheet() Styling a label is done using the Qt Stylesheet. Using the setStyleSheet() function we specify the properties of our label's stylesheet in a single string. The variable myLabel is prefixed so that the function knows which stylesheet its changing. Each property of the stylesheet is separated with a semicolon. There are numerous things you can do with this and a full list of features can be found here: [1]
2. Stylesheet contents setStyleSheet() has but a single parameter: a single string containing every property of the stylesheet. This single parameter is encased with double brackets as there may be a string within a string. In our example, we have only provided a single property: background-color. Each property is separated from it's value with a colon.

Vyzor

Blah Vyzor Blah

Create a Clickable Compass

The following will walk you through the process of creating your own clickable compass using the Geyser framework.

Create a new script

Script Name: compass.resize

Registered Event Handlers: sysWindowResizeEvent

Every snippet of code will be placed within this script.

Store the screen size

We'll want to store the screen size in some local variables so they can be easily referenced to later on. <lua>local mw, mh = getMainWindowSize()</lua>

Create a global table or namespace

Creating one will make each of your variables unique. Our namespace will be called compass and everything we make from here on out will be stored within the compass table. We'll also add a few values to it: dirs and ratio. compass.dirs will store each direction while compass.ratio will store the ratio of our screen size so you can 'square up' your compass. <lua>compass = compass or {

 dirs = {"nw","n","ne","w","center","e","sw","s","se"},
 ratio = mw / mh

}</lua>

Create the parent label

The 'parent label' refers to the label on the bottom layer. The entire compass will be created within this label. It's container is main for it's parent is the main window. <lua>compass.back = Geyser.Label:new({

 name = "compass.back",
 x = "25%",
 y = "25%",
 width = "10%",
 height = "10%",

},main)</lua>

Set the parent label stylesheet

This will create the blue sphere that makes up most of the compass. The background color is a radial gradient that goes from a deep blue to a brighter shade. The border radius rounds the edges. When the radius is exactly half of the label width it forms a circle. The arrows of the compass actually protrude from the sphere so we give it a margin to suck it in a bit for this effect. <lua>compass.back:setStyleSheet([[

 background-color: QRadialGradient(cx:.3,cy:1,radius:1,stop:0 rgb(0,0,50),stop:.5 rgb(0,0,100),stop:1 rgb(0,0,255));
 border-radius: ]]..tostring(compass.back:get_width()/2-14)..[[px;
 margin: 10px;

]])</lua>

Create a 3x3 grid

The compass is split into 9 sections. One for each cardinal direction plus an extra space that sits in the center. This 3x3 grid is created by 3 VBoxes that sit within a single HBox (or vice versa but I flipped a coin and this is what it gave me).
So first off, we create the HBox. It will be the same size as its parent, compass.back. <lua> compass.box = Geyser.HBox:new({

   name = "compass.box",
   x = 0,
   y = 0,
   width = "100%",
   height = "100%",
 },compass.back)</lua>

Next, we create our 3 VBoxes. You don't need to specify position or size because these are placed within compass.box, an HBox. <lua> compass.row1 = Geyser.VBox:new({

     name = "compass.row1",
   },compass.box)
   compass.row2 = Geyser.VBox:new({
     name = "compass.row2",
   },compass.box)
   compass.row3 = Geyser.VBox:new({
     name = "compass.row3",
   },compass.box)</lua>

Finally, we add our 9 labels. Take note that they are split up into even groups of 3. Each group is placed into a different compass.row# <lua> compass.nw = Geyser.Label:new({

       name = "compass.nw",
     },compass.row1)

     compass.w = Geyser.Label:new({
       name = "compass.w",
     },compass.row1)
   
     compass.sw = Geyser.Label:new({
       name = "compass.sw",
     },compass.row1)
 
     compass.n = Geyser.Label:new({
       name = "compass.n",
     },compass.row2)
       
     compass.center = Geyser.Label:new({
       name = "compass.center",
     },compass.row2)

     compass.s = Geyser.Label:new({
       name = "compass.s",
     },compass.row2)

     compass.ne = Geyser.Label:new({
       name = "compass.ne",
     },compass.row3)
   
     compass.e = Geyser.Label:new({
       name = "compass.e",
     },compass.row3)
 
     compass.se = Geyser.Label:new({
       name = "compass.se",
     },compass.row3)</lua>

Create a callback function

We'll want our compass to head in the direction of the arrow we're clicking. This is where we specify so. When the arrow is clicked, this function will be ran with the arrow direction as the argument. <lua>function compass.click(name)

 send(name)

end</lua>

Create the hover functions

We want our arrows to turn yellow when we hover over them. We do so by simply resetting the label's stylesheet and changing the border image. Don't forget to include the margin as we still want that. <lua>function compass.onEnter(name)

 compass[name]:setStyleSheet([[
   border-image: url("]]..getMudletHomeDir()..User talk:Akaya/..name..[[hover.png");
   margin: 5px;
 ]])

end

function compass.onLeave(name)

 compass[name]:setStyleSheet([[
   border-image: url("]]..getMudletHomeDir()..User talk:Akaya/..name..[[.png");
   margin: 5px;
 ]])

end</lua>

Set the stylesheets in the grid

Each of the 9 labels need an image of an arrow. Rather than setting each individually, we'll iterate over the compass.dirs table we made awhile back and add the respective image to each. The names of images are a reflection of the compass.dirs table. This keeps it consistent and easy to refer to. During the iteration, the callback, setLabelOnEnter and setLabelOnLeave are also set for each label. <lua>for k,v in pairs(compass.dirs) do

 compass[v]:setStyleSheet([[
   border-image: url("]]..getMudletHomeDir()..User talk:Akaya/..v..[[.png");
   margin: 5px;
 ]])
 compass[v]:setClickCallback("compass.click",v)
 setLabelOnEnter("compass."..v,"compass.onEnter",v)
 setLabelOnLeave("compass."..v,"compass.onLeave",v)

end</lua>

Resize the compass into a square

Most screen size ratios aren't a perfect 1:1. This will cause a 10% x 10% label to be far from square. By multiplying our height (the smaller of the two numbers) by our compass.ratio we set earlier, we can resize our compass to a near perfect square. This function is also the name of our script because we want it to run each time sysWindowResizeEvent is raised. <lua>function compass.resize()

 compass.back:resize(compass.back:get_width(),math.floor(compass.back:get_height()*compass.ratio))

end

compass.resize()</lua>