asume Wiki - asume

Asume (Altap Salamander User Menu Editor) - The Smalltalk/X-jv branch open-source project

(most probably the first standalone open-source application for Smalltalk/X)

My contact details

patrik<dot>svestka<a7>svestka.biz

To download a portable version

To download a portable version go to releases section and select a asume_portable_x.x.x.7z where x.x.x is the version you want.

Checksum - verify you have unaltered version

sha256 checksum file

---

Description

Reads the flat tree structure of the Altap Salamander User Menu from Windows registry. The registry path is based on the user and salamander version combination. If no such combination can be found the user can enter the registry path manually. The flat tree is converted to a regular tree structure which can be arbitrary complex.

The user can manipulate the tree any way preferred. After the editing is complete user can decide whether to export it to a registry file (*.reg) or save it directly back to the Windows registry.

Note: Do not forget that if you have Altap Salamander setup in a way that it always saves the settings, you need to close all your Altap Salamander instances prior saving changes into Windows registry. Otherwise your changes could be overwritten.

Features

• Virtually unlimited tree depth
• The whole application can be controlled either only via keyboard or mouse (for typing you would have to use some virtual keyboard)
• Multiple users (having Altap Salamander installed)
• Multiple salamander versions
• Unicode (UTF-16) is supported; since Altap Salamander does not support Unicode you will get probably some weird characters
• Moving (up, down, in, out) multiple nodes selection at time
• Copy, Cut and Paste
• Node is created just below selected line (at AS it is always created at the end, which can be annoying)
• The pop-up menu with salamander variables is available exactly the same as it is at Altap Salamander
• Every action can be done via mouse, menu, shortcuts, toolbar and adding/removing via pop-up menu - find what suits you the best
• The validation checks - user is warned when required information is missing
• The consistency checks - when doing a save to the Windows registry there is a backup of the current menu before actual save takes place. When a save is successful then the backup is removed.

Dedicated

This application is dedicated to the memories of my mom who passed on during its writing.

My wholehearted thanks to

• Hanička - My wife :0)
• Jan Vraný - The maintainer of Smalltalk/X-jv branch. Thank you for your Smalltalk/X insights!
• Claus Gittinger - The original creator of Smalltalk/X.

A wish to come true

I wish for the VM and STC of the Smalltalk/X to be released as open-source. It would be great addition to the world of Smalltalk programming. It would greatly improve the Smalltalk/X for the eXept too, if one could send patches for it.

Properly tested

This application is covered by more than 270 tests. This does not include more than 100 tests that cover reading/writing to Windows registry - now included with Smalltalk/X-jv branch. All together this application has more than 370 tests to cover its functionality. I have tested the application on Windows 10 x64 and Windows 7 x64 so for these it is properly tested.

Of course, that does not mean there are no bugs, it only means I do not know about them.

Todo

• view icons when selecting them and at the tree - *.ico, *.dll, *.exe - this will take longer as support has to be written in C

Possible features in the future (not planned but considering it)

• detect 32-bit salamander installed on 64-bit windows (only if there is a strong demand for it)
• create 32-bit version (I do not needed it personally, but if someone needs it and supports me, I will create it)
• drag &amp; drop support
• mass rename - prepend and postpend a string
• implement undo/redo for the application

Missing features

• no HiDPI support because it is currently no supported at Smalltalk/X. If Smalltalk/X environment will get it so can the asume application.

License

I have decided to go with Creative Commons 4.0 (CC) license basically for the reason that I am using icons that are using CC too. Please be sure to read the license at the ASIconLibrary class source code for you to be compliant with the icons' license.

---

How to compile the source code

First you need to compile yourself a Smalltalk/X-jv branch environment. The best way is to do it via this guide Building Smalltalk/X with rake files.

When the environment is ready then you need to follow these steps:

1. change to the C:\<smalltalkx_install_path>\build (e.g. C:\prg_sdk\stx8-jv_swing\build)
2. create there an directory ps and change to it
3. clone the asume's source code from the repository: hg clone https://hg.osdn.net/view/asume/asume
4. run cmd.exe (in case PowerShell is started)
5. execute ..\..\..\bin\setenv.bat which sets your environment
6. run mingwmake
7. now you should have an asume.exe file in your source code directory which can be executed

To create a new version and standalone application

1. merge all your branches to a default branch
2. run ruby script ruby version_bumper.rb with a correct switch (--bugfix, --minor, --major) that applies to the changes made
3. now compile the application (steps 5. and 6.) in the cmd.exe shell
4. run a powershell script .\create_standalone_application.ps1 (do not forget to change paths within) script that creates complete standalone application. (also executes add_icon.bat which adds icon to the executable from the *.ico file)

---

Technical details - the Smalltalk/X-jv journey

There were some challenges along the road when creating this application. I will describe the most important and my approach in dealing with them.

1. The invisible text

The first one was mysteriously disappearing text. For complete history you can visit the #126 Copy to workspace (same thing in the Inspector) this line - becomes invisible (only when selecting via mouse it appears) ticket.

The description of the fix:

On windows (7 and up) there is undocumented, you can not find this information anywhere, limit for raster size when using TextOutA or TextOutW. Experimentally, I have come to the conclusion that the limit is most likely set to 16384 points of the raster. To correctly calculate the maximum display buffer (maxDisplayBuffer) I have come to a formula:

maxDisplayBuffer = 16384 / (maxWidth + tmet.tmOverhang);

• maxWidth is the maximum selected font width
• tmet.tmOverhang is the "extra width per string that may be added to some synthesized fonts." If you want to get the actual width you have to add it to maxWidth. You will get the whole extent then. (Note: For most fonts tmOverhang will be 0.)

The whole definition of tmOverhang is the following (from MSND about TEXTMETRIC structure):

tmOverhang
The extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

In very rare case there is something wrong with GetTextMetricsW(hDC, &amp;tmet) there is a fixed maxDisplayBuffer = 107;. (Smaller buffer would be extremely slow and larger could lead again to disappearing text). This value was derived from all 1170 fonts installed on my computer and computing avgWidth for all fonts size 96pt (In my eyes, this should suffice 99.9% of times. When was the last time you have used 96pt font and above for extremely long strings?)

2. The Unicode text to be read/written form/to registry

The Windows registry is naturally Unicode (UTF-16). The Smalltalk/X-jv had some issues when it came to the reading/writing to Windows Registry.

Reading from Windows registry

First I fixed the reading from Windows registry - #250 Smalltalk/X is reading Windows Registry only in ASCII but registry is UTF16. There I have provided a set of patches that fix libbasic to correctly read Unicode strings from the registry

Writing from Windows registry

Second came writing to the windows registry #252 Smalltalk/X is writing Windows Registry only in ASCII but registry is UTF16. Same as reading I have provides set of patches to libbasic and tests.

Note: What needs to be noted I tried to stick to the original code as much as possible and there is one thing that needs to be addressed. In the function #valueTypeAndSize: there is automatic detection if the written value will be either DWORD or QWORD based on dataSize. This can nuisance when a user would like to write a DWORD sized variable into QWORD directly. If there is such a need this code needs to be re-factored and enable user to specify the registry type.

Summary for the Unicode read/write to the registry

With the patches I have provided over 100 tests to be sure, of course only to some extent, that the reading and writing is done correctly.

3. Renaming registry subKey - the choice is either to use undocumented or obsolete function

Renaming subKey (#renameSubKey:to:) functionality is used during a save. The save process renames the current subKey to have a backup to rollback to. To my surprise there is no current documented function to rename a subKey, apparently Microsoft forgot to document it. It comes down to either use undocumented RegRenameKey or NtRenameKey which is currently marked as obsolete. I have decided to use RegRenameKey as first choice having NtRenameKey as a fallback.

4. Sublime text Smalltalk/X source code syntax highlighting

For my Smalltalk/X embedded C programming I have created even a highlighting file for the Sublime Text 3 editor - Sublime Text 3 highlighting for Smalltalk/X