Building a GtkMenubar

Here is a quick overview of how to build a menu bar using php-gtk2 widgets. Think of it as a cheat sheet on menubar and friends.

The goal of this page is to list the most important objects and methods needed to build a basic menubar. You can use this document to write your own function or menubar class builder. We try to keep this document as simple as possible, not to show all advanced mechanisms.

Widget tree

Here is a complete widget tree with some useful information

• tree level ; you can find this level on source code comments,
• php variable name (sometimes)
• Gtk class related
• variable or strings instance in source code below
• methods available to build object tree

# widget tree (or relations) :
  0 - $window  (GtkWindow) -> add()
    1 - $menubar  (GtkMenubar) -> append() or add()
      2 - $item  (GtkMenuItem) (File, Edit) -> set_submenu()
        3 - $menu  (GtkMenu) ($quit_menu, $file_menu) -> append() or add()
          4 - $menu_item (GtkMenuItem|GtkSeparatorMenuItem|GtkRadioMenuItem)

and here is the expected widget representation on your screen

  menubar:
    File
      New
      Quit
    Edit
      Cut
      Copy
      Paste
      ---
      - Choice 1
      * Choice 2 (activated)
      - Choice 3

Details

Here is a complete source code example. For this example, code indentation is relative to the object tree hierarchy, not to the code structure as usual. A few points :

1. to build a group a toggle buttons, give null to first widget in a group, and the first widget in successive widget creations.
2. you can use either append() or add() methods without significant changes.
3. default value is "choice 2" for radio buttons ; see the set_active() method,
4. for button, use "activate" signal,
5. for toggle buttons, the signal to catch is "toggled",

Links

Examples

• GtkMenubar example in the PHP-GTK reference,
• GtkRadioMenuItem example in the PHP-GTK reference.

API

• GtkMenubar,
• GtkMenu,
• GtkMenuItem,
• GtkRadioMenuItem,
• GtkSeparatorMenuItem.

  menubar:
    ...
    View
      Line
      Border
      Toolbar
      ---
      Zoom
        50
        100
        150
      ---
      Scrollbar

  0 - $window  (GtkWindow) -> add()
    1 - $menubar  (GtkMenubar) -> append() or add()
      2 - $view_item  (GtkMenuItem)  -> set_submenu($view_menu)
        3 - $view_menu  (GtkMenu) -> append() or add()
          4 - $view_zoom_item (GtkMenuItem)
            5 - $zoom_menu (GtkMenu) -> append()
              6 - $view_zoom_50_item  (GtkMenuItem)
              6 - $view_zoom_100_item (GtkMenuItem)
              6 - $view_zoom_150_item (GtkMenuItem)

CommandWidget - a terminal like widget for php-gtk

The CommandWidget is nearly like a terminal and allows the user to issue commands to a shell and view the result in a GtkTextView widget.

Details

This widget can be used if you want to run some commands in the background and never use any more any printf. Or if you have some text output at console the and would like to see it in a window. CommandWidget can do that for you.

CommandWidget is a external process or a shell connected to a GtkTextview to display results. This connexion is made throught a pipe. You can read and write to this external process. This can be a (nearly) full interactive process, just like terminals (command.com for Windows). There is a special class with output only and really easy to use. It could be used to proide feedback to some management tasks using external commands (say, tar for example).

Example of use

The code below wil create a window just like the one on top of this page. You can send commands using the text entry field at the bottom of the windows, and the results are displayed on the top part (a GtkTextView widget). Text color is higlighted for commands and errors.

ShellCommandWidget

ShellCommandWidget is a derived class to simplify usage for text output only for external commands. This widget has no entry widget, so commands can only sent from a script. This widget creates a pipe with a standard shell waiting for commands to be executed. Here is an example of use (this is a bit similar to CommandWidget:

Full source code

See the attached sources file below

Bugs

See on source code header

Desktop Gadget - a small widget moving around your screen

The DesktopGadget is a small window moving around you desktop screen ; it's a container widget and is able to contains usefull object for short information or notification.

Details

DesktopGadget is :

• as small as possible and display short messages or notification ; in given code, this is just a literal clock ; I intend to build a Google calendar gadget notifier.
• this visual gadget is movable all arround the screen ; there is some options in script code to change display and position (on top, on desktop ...)
• position is saved in a configuration file using Config class
• given code is fully object oriented and allow some changes
• if you can write some php-code and have some Gtk skill, you could be able to write some (un)usefull gadgets.

The most interesting part of code is at the end and show you how it's very easy to add some gadgets :

Restrictions

You should have write acces to directory where this script is running to save gadget position.

Source Code

source code is provided as a link below for free as LGPL licence ; also available here

Links

• GtkWindow API : set_skip_taskbar_hint, set_skip_pager_hint, set_keep_above, (un)stick, set_decorated and custructor

Todo

• write some gadgets : google calendar, hosts pinging, email watcher for example
• write a configuration interface

Dial widget - a graphical widget to display an analog value.

The Dial widget is a graphical object which displays an analog value. This is a direct port of the Gtk tutorial about creating graphical widgets

Details

The Dial widget can display a value from -120 to 120. This could be changed, just write the right mathematical operations (I'm a bit lazy, guys). This widget can draw directly into a Window (direct drawing) or draw into a pixmap, which we can then refresh as needed ; just look at the class source code to see how it is done.

Direct draw is much faster for large windows ; I can't see differences for small ones. The actual graphical part (drawing the dial) is a php-gtk port from the Gtk tutorial. This widget is a good start when you need to build dynamic graphical widgets like this one.

Example of use

Highlights

1. create a dial widget,
2. add this widget to a composite widget (any composite can be used)
3. setup a timeout function to update the dial value
4. set the dial value with $dial->set_value($val)

Full source code

See the attached sources file below

Easily empty GtkContainer/GtkWindow

This function provides an easy way to empty a GtkWindow/GtkContainer. I use it when i need to refresh a part of my app by replacing some widgets with others. It can destroy or preserve the child widgets depending on your needs.

Sample usage

Note: This is a rewrite for php5/php-gtk2 of the same function i've already poster for php4/php-gtk1. Hope this will be helpful to you.

function empty_widget

Editable cells within GtkTreeView

Intro

this script is based on example in the PHP-GTK 2 manual, which was left unfinished. So here is a working example with editable columns.

With editable cells, you can display cells, and edit cell content in the same place. This is a very convenient way to manage list of items without having to popup some boring editor window. To edit text cells, you just need to click a second time on an item when it has been selected.

Details

To make cells editable, you just need to set GtkCellRendererText object as editable :

then connect a signal callback function to the "edited" signal; this callback will update the data model

For toggle renderers, connect "toggled" signal and swap the toggle state.

Source code

Extending GtkDrawingArea with OO methods

This example shows a nice drawing area class, derived from GtkDrawingArea:

• with 2D matrix transformation : rotate, translate, scale
• with many classes : Point, Matrix, GxObject, GxPoint, GxRectangle, GxDrawingArea

This framework is not complete, but marks the first snapshot for a drawing editor done in php-gtk2. The main part of the code is in the "timeout" function (GxDrawingAreaTest class).

A more complete library can be found at : http://quinton.free.fr/php/gtk/gxlib/. There is now a near working drawing editor and some tutorial-games applications (brick-breaker, snake, tetris ...). Please, note : this code below is a little outdated.

Extending GtkFileSelection : the FileSelectionDialog class

This FileSelectionDialog provides a wrapper around the standard GtkFileSelection class in PHP-GTK2, to make it easier to use.

Note : you can check a simpler introductory example to GtkFileSelection before delving into this class.

Main methods :

• hide()
• show()
• get_selection() : return file section if OK pressed, return false if cancel button is pressed. (see usage below)

Quick overview (usage)

You can see how it easy to get a file ; all you need to do is to create a FileSelectionDialog instance and call the get_selection() method.

Complete class code

Extending GtkMenu class for Popup menu dialog

Here is a quick way to build a popup menu supporting event registration from a GtkWidget. Menu items are passed to the class constructor as a list of labels. This class emits activate signals with full context (x,y coordinates, button ...).

See example below for basic usage.

Details

1. create Gtk standard stuff,
2. create a Popup menu in a single a simple line with 3 items (Edit, Cut, Paste),
3. connect an "activate" callback
4. some items can be unsensitive depending on application context,
5. set parent widget ; this widget must contain a Window to register some buttons events. No warning about that in this current code, but could be done,
6. look at activate callback ; complete event context is available, containing (x,y) coordinates ; may be usefull in some usages.

Example

Class code source

Updates

• added Popup::set_parent() method to avoid simplify event and signal registration. This is done by this method.

Extending GtkToolbar to quickly build toolbars

A very easy way to build toolbars with icons, tooltips and an easy signal connect feature.

Details

Building GtkToolbar with buttons icons and tooltips require :

1. creating a GtkToolbar widget,
2. creating some GtkToolbarButtons from an external icon file,
3. buttons can use stock icons (from systeme library),
4. insert button to toolbar,
5. setting up GtkTooltips to each buttons ; there must be only one instance of GtkTooltips object.
6. setting up clicked signal callback to each buttons.

all this tasks can be made in a quick way with Toolbar class. Look at example below; snapshot shows you the execution result.

Example usage

1. this is a standard menubar in english,
2. you can control attributes of toolbar button (label, tip, icon)
3. an other toolbar description in french
4. note defaults values
5. french labels (external part visible for user) and english internals (coder)
6. standard php-gtk windowing construction
7. create a first toolbar with first description array, and set some toolbar attributes just as if Toolbar was a Gtktoolbar
8. connect a signal callback for clicked signal,
9. a second tooolbar localised in French,
10. the signal callback ; have a look a function signature.

and that's all

Source (Tooltips)

This class is from Callicore project with a nice php-gtk2 framework in construction. You can't use multiple instance of GtkTooltips ; if you do, tooltips seems not working. So the choice here is to build a Singleton class using standard GtkTooltip.

Source Toolbar

here is full source code for Toolbar class with instructions in comments.