XFree86/2 - Enlightenment/2 User's Guide

Crazy creation of color-blind Linux people, who enjoy sex in a hammock with a diving suit on them...
calc enlightenment on #os2russian by banshee


Welcome to E/2 user's guide. This guide is written for end users to simplify the task of installing Enlightenment and will give you some basic knowledge of how to use many features integrated in E/2. The document is divided into seven sections:

  1. Overview
  2. Getting E/2 and short description of "who's who"
  3. Installing E/2 and possible problems
  4. Basic skills with E
  5. E/2 specific things
  6. Epplets
  7. Additional info

Overview

First of all let's clarify everything. Enlightenment is an XFree86/2 application. It is designed to be used only on XFree86/2 and only on OS/2 Warp 3|4|WSeB. The task of setting X/2 and configuring it is beyond this document, so if you are just want to look at E/2 think about installing X first. And more.. I am not going to port E to PM, but it is possible. Good knowledge of X and OS/2 PM are of course the requirements for any coder who is going to start this project.

WARNING! Before you proceed with E/2 installation let's check some basic info about your system.

Real recommendations:

  1. IBM PC machine with Intel architecture processor 133 or higher
  2. IBM OS/2 Warp 3|4|WSeB (*1) with MMOS2 installed
  3. XFree86 3.3.3.1 or higher. (*2)
  4. 48 MB of RAM. (*3)
  5. Accelerated X server (not generic SVGA (*4)) in 16 or 24 or 32 bpp while using X, 8 bpp is too small and look bad.
  6. 3 Button Mouse - yes - this is a MUST one if you want to work in E/2, of course you can use 2 Button mouse too - but third button will be emulated through quick pressing of both buttons and I know it is awful thing IMHO.
  7. HPFS or HPFS386 or FAT32(?) file system
  8. EMX 0.9d fix 2 or 3 runtime

Who's who

Here I will explain what each file does.
/XFree86
First of all E/2 uses /XFree86 root directory as basic and will not work without it. And no other chances. You need to have /Xfree86 dir for E/2 to work ok.

/XFree86/bin
the directory where enlightenment binary is - it is called enlightenment.exe :), also in /bin dir there are some menu generation utils and some epplets. All epplets have the extension .epplet

$HOME/.enlightenment
type SET HOME to get info where your home directory is. In it you typically can see:

Directories:

  • backgrounds - this is a directory where you will place backgrounds for fast access and fast switch
  • cached - contains some vital info to speed up E's loading & work
    • bgsel - backgrounds scaled for configuration notebook
    • cfg - conifuration files processed through E compiler
    • img - backgrounds and other images scaled for menu view
    • pager - backgrounds scaled for pager view
  • epplet_config - epplets write their stuff there
  • gnome_icons - gnome icons scaled for menu view
  • menus_gnome - contains ".menu" files for gnome apps (see "menu" format)
  • themes - here you can place tgz'ipped or untg'zipped :) E themes
Files:
  • ...e_session-XXXXXX - weird system file no maintaince plz ;) in general it contains info about remembered settings,keys and so on.
  • ...e_session-XXXXXX.snapshots.0 - weird system file no maintaince plz ;)
  • .initialized - you may look into this file. BTW this file is an interesting one, by deleting it, you may re-initialize E.
  • .zoom_warn - you may look into this file.
  • epplets.menu - epplets menu
  • file.menu - one of E main menus
  • gnome.menu - Gnome menu
  • gnome_user.menu - Gnome User Menu
  • user_apps.menu - General X applications you may have
  • user_theme.cfg - A file which is a pointer to current theme.

/XFree86/lib/X11/enlightenment

Directories: (you may not have some of them)

  • config - Some GENERAL defaults for E
  • E-docs - Enlightenment documentation
  • epplet_data - Epplets data
  • epplet_icons - Epplets icons
  • fonts - General fonts for E system use
  • themes - Themes directory (here you will see all themes you have)

/XFree86/lib/X11/enlightenment/config

Directories:

  • pix - Common pictures for settings and tooltips
Files: (Please read E theming tutorial on info about this files)
  • actionclasses.cfg
  • control.cfg
  • definitions
  • icondefs.cfg
  • keybindings.cfg - You can dig up in this file - it is pretty understandable
  • keybindings.gmc.cfg
  • keybindings.nogmc.cfg
  • menus.cfg - You can dig up in this file - it is pretty understandable
That's all folks about E files and dirs.

Installing E/2 and possible problems

Getting

Installing E/2 is not easy most of all because I am damned lazy man :) I do really hope someone will construct .wpi for E so this section will become obsolete, meanwhile let's start digging into UNIX-way on OS/2. Well you need lot's of libraries that will help E/2 to operate, also some ports from UNIX and a shell... Let's try to summarize:

  1. Shell: any shell will do,except cmd.exe. Btw with E/2 comes a package called E-Support.zip there you will find shell which I use.
  2. Programs: (you will find most of them on hobbes and all in E-Support.zip)
    • awk - pattern scanning and processing language
    • grep - search stdin or files for pattern
    • head - print first 10 lines of each FILE to standard output
    • tail - print last 10 lines of each FILE to standard output
    • tr - translate, squeeze, and/or delete characters from standard input
    • which - search for application in %PATH%
    • ps - list processes
    • basename - get absolute file name without its path
    • sed - stream text editor
    • touch - update files date to current one
    • rm - remove files and/or directories
    • cp - tremble copy command as cp is much more powerful ;)
    • mv - move files
    • mkdir - make directory
    • gzip - good old file packer
    • tar - file archiver
    • Recommended bzip2 - good new file packer
Seems it is all you need, but imho it is much easier to install ALL packages from hobbes like gnu file utils, gnu text utils, gnu grep and other gnu things to keep yourself from future troubles.. Someone may say "what a bunch of crap" - hey-ho laddy indeed it is, but you want to have E/2 up and running so keep busy downloading software and even more some commands like rm -r * can do lot's of cool things ;)

Now for libs, they are all in fact .DLL files.

Graphics subsystem:

All libs are shipped separately
  1. ImageMagick a huge but very useful tool itself, it is a must for server based image operations from a command line.
  2. GIF lib
  3. PNG lib
  4. JPEG lib
  5. TIFF lib
  6. Imlib195 Lib - special lib for E and GTK with its own config and tools.
  7. MESAGL lib for epplets

Fonts subsytem:

All libs are shipped separately
  1. FreeType lib

Additional files for E:

E16MenuEditor & E16KeyEditor both require GTK 1.2.8 but are very useful - a simple menu editor and a simple key editor.

Shared Memory latest library. Latest shm.dll can always be found at birdy.hpage.net and is extremely necessary for X 3.3.1 users.

Installing

Well I recommend first getting ALL you may need and that's a lot as you may see, after that save it all in an "Archive" directory and start installing. If you still haven't got X up and running it is very bad and sad.. loop at this point until you will have X running in 16bpp with your old rusty window manager ;) This assumes btw that EMX is also installed, please double check its version and upgrade if needed. Unzip graphic libs, font libs, imlib195 and finally huge E/2 package in /XFree86 tree. Correct xinitrc.cmd so it will start 'enlightenment' and check that you do not have .enlightenment or other similiar directories in your home dir. If it exists please wipe it out.

Now for a brief test:

E-Support package comes with "ldd" tool for checking up executables and dlls. Type ldd enlightenment.exe in /XFree86/bin dir and check your output it may be like this: 

Loading DLL 'emx' --> E:\OS2\DLL\EMX.DLL.
Loading DLL 'EMXLIBCM' --> E:\OS2\DLL\EMXLIBCM.DLL.
Loading DLL 'intl' --> F:\XFREE86\LIB\INTL.DLL.
Loading DLL 'X11' --> F:\XFREE86\LIB\X11.DLL.
Loading DLL 'Imlib195' --> F:\XFREE86\LIB\IMLIB195.DLL.
Loading DLL 'XEXT' --> F:\XFREE86\LIB\XEXT.DLL.
Loading DLL 'SHM' --> F:\XFREE86\LIB\SHM.DLL.
Loading DLL 'XTST' --> F:\XFREE86\LIB\XTST.DLL.
Loading DLL 'SM' --> F:\XFREE86\LIB\SM.DLL.
Loading DLL 'ICE' --> F:\XFREE86\LIB\ICE.DLL.
Loading DLL 'libaudio' --> F:\XFREE86\LIB\LIBAUDIO.DLL.
Loading DLL 'ttf' --> F:\XFREE86\LIB\TTF.DLL.
Loading DLL 'doscalls' --> loaded.
Loading DLL 'mdm' --> E:\MMOS2\DLL\MDM.DLL.
All DLL's used by 'enlightenment.exe' could be loaded.

See the last line :) This is your goal too. Now check that cp,rm,tar,gzip and other gnu utils are in path and may be run from anywhere on drive. Time to work with XF86Config - find it and open for edit mode, add now this lines in your video card definition to make Zoom feature work ok: Modes "1600x1200" "1280x1024" "1152x864" "1024x768" "800x600" "640x480" "512x384" "400x300" "320x240" an example: 

Section "Screen"
  Driver "accel"
  Device "ATI 3D Xpression"
  Monitor "My Monitor"
  Subsection "Display"
    Depth 8
    Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768"
    ViewPort 0 0
  EndSubsection
  Subsection "Display"
    Depth 16
    Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768"
    ViewPort 0 0
  EndSubsection
  Subsection "Display"
    Depth 24
    Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768"
    ViewPort 0 0
  EndSubsection
  Subsection "Display"
    Depth 32
    Modes "640x480" "800x600" "1024x768"
    ViewPort 0 0
  EndSubsection
EndSection
Now run X and see what will happen ;)

Possible problems

And a hell lot of them my friends... Although most of users do not have E/2 troubles you may be the one who have them all.
  1. X Server crashes
    Possibly old server, and most possibly old shm.dll
  2. Wrong colors
    Possibly incorrect switch to 16bpp start X Windows this way "startx -- -bpp 16"
  3. Strange dialog box with error
    Error ;) Send it to me no more
  4. Illegal fonts
    Study theme creation procedures and change fonts the way you like.
  5. Menu creation failure
    Get ALL utils I asked you to get, check sh.exe can be run.
  6. No icons in menus
    Install ImageMagick!
  7. E/2 starts after a big pause
    X/2 bug not mine - bomb Mr.Holger Veit with this bug, may be he will fix it ;) Btw you can install Samm's RxStartx which can launch XFree86 up to 2 times faster.

Basic skills with E for people that are not going to read docs :)

Well E has a extremely good help system imho - I urge you to read it, but alas you may miss some points.. So I point here the most useful and most not-so-obvoius things:

Using Menus

To "stick" a menu up and leave it up so you can select items from it multiple times, click and hold down the mouse and release on the title of the menu (if it has one) and it will remain up. You can move it and manipulate it like a normal window. Close the window to unstick the menu.

Moving Windows without titlebar

If you hold down the ALT key and hold down left mouse button anywhere in the window (on the border OR in the application part) while dragging, you will move this window around. Doing the same but with the middle mouse button will resize the window in that direction. Clicking the right mouse button anywhere in the window while holding down the ALT key will bring up the window operations menu.

Useful Keys

CTRL+ALT+(F1 - F12) - Go directly to desktops 0 - 11
ALT+Tab - Switch focus to the next window (only when XKB is enabled)
ALT+Enter - Zoom/Unzoom the currently focused window
Also I made myself a good key combination using E16MenuEdit util from E-Support package and a go.exe application. I mapped windoze key to a command "go -j pmspool.exe", thus pressing this key I move from X to PM without Ctrl-Esc sequence
CTRL+Alt+ESC is also a useful combination it kills all X in one second ;) good when X is hanging
CTRL+Alt+Shift+"+" and CTRL+Alt+Shift+"-" can quickly switch you between video modes

E/2 specific things

Well E themes can be unpacked using untgzos2.exe from E-Support package or with gzip and tar. Installation of them is too quite simple - just copy compressed theme in /XFree86/lib/X11/enlightenment/themes or uncompress theme in this dir. Uncompressing the theme you speed up loading of E/2 a lot btw.

Epplets

Epplets introduce new package for E/2 users to enhance their life with small yet beautiful and useful programs ;) 50% of core code of most of Epplets was wriiten to use specific OS/2 API's for better perfomance. Also some epplets are set to work on idle priority.

What epplets are in the package?

Many ;) But not ALL ! For example E-CD applet was dropped because I do not know how to program CD operations in OS/2. So here is the list:

How to install?

Unpack to /XFree86 tree and in E/2 launch Menu Regeneration (New menu-gen-scripts are also added to this package) (User Menus -> Enlightenment Epplets)

Sources?

All epplets are open-source if you want to make modifications. Sources are included as there are many changes, too many for diff

E-MemWatch

You will need latest THESEUS installed to correctly see Swap statistics.

Open-GL Demo

It needs MESA libs to work

Additional info

Setting up ESD

Just run esd.exe before running XFree86/2. You should hear some lovely ;) tunes. Next time use -nobeeps option to make esd silent. If you want you may modify xinitrc.cmd to start esd every time X starts. After that enable sound in E/2.

Locale things

E comes with locale support so it supports messages in your language. Just check /XFree86/lib/X11/locale/Your Language i.e de Warning! Not all themes have fonts that support all your letters. If you do not want to use E locale support please delete /XFree86/lib/X11/locale/Your Language/LC_MESSAGES/enlightenment.mo

Menu generation issues & GNOME/2

E/2 will automatically construct menus for you at first startup. If you will have troubles with GNOME/2 please download gnome2-apps_tree_for_E.zip to get full GNOME/2 application tree.

Credits

I wish to express my deepest gratitude to Mr. Hung-Chi-Chu for doing first work on E/2 0.15.5 and for starting the port itself. I do not know now where is he , what is he doing now and nothing can stop my grief.He disappeared so suddenly and for a year I heard nothing about him. He was the MASTER of porting. I miss him so much.

Christopher Vogelbusch is the person who made E/2 available to millions, thanks Chris!

Alex Galkin kept me busy testing E/2 code.

10X! (Thanks)

Holger Veit for doing XFree86/2 :)
....hmm.. heh....what the hell for..eeek...damn... IBM (only OS/2 loyal people) for OS/2 ;)

I also want to thank some people on #os2russian && #os2warez: [Nuke] es Alexx banshee _mda_ Samm dip Euxx Chill |AlexV| OS2OK Ltning and all others!

Footnotes

(*1) to use XFree86/2 on Aurora you need to get latest version 3.3.6
(*2) basic 3.3.3.1 server has serious problems with component called SHM (Shared Memory Module), please go to http:\\birdy.hpage.net\ and get fixed server. New 3.3.6 server do not have integrated TrueType support which results in need of a special X TrueType font server for apps that use TrueType fonts. (For example you want to use TTF fonts in GIMP/2). E/2 does not need TTF font server as it can render TTF fonts itself.
(*3) if you are a lover of big JPEG's, TIFF's and PNG's as a background, you plan to use many desktops and different backgrounds for them get 64 or better 128 Mb of RAM.
(*4) please remember SVGA server supports lots of cards in accelerated mode! study docs and understand how fully your card is supported. SVGA generic support will result in awful perfomance ;)

Support, help, docs and bugs: Platon Fomichev or Stauff__ at pla@cland.ru
E/2 site: birdy.hpage.net

That's all folks! May the Source be with you ;)

Platon Fomichev (C) 2000