Mercurial > dwindows
annotate style.txt @ 2630:7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
author | bsmith@81767d24-ef19-dc11-ae90-00e081727c95 |
---|---|
date | Sun, 01 Aug 2021 22:23:48 +0000 |
parents | |
children | 3d20fcfd8583 |
rev | line source |
---|---|
2630
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
1 === Code Style and Design === |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
2 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
3 --- Design Principles --- |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
4 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
5 To explain the existing style and where we are going it makes sense to explain the history of Dynamic Windows. There are several design principles that Dynamic Windows adheres to: |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
6 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
7 1) Compatibility, Portability |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
8 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
9 C was chosen as the API because essentially every platform has a C compiler. Even when the internals are written in another language, like C++, Objective-C or Kotlin/Java, the exported API is portable C that can be used on all the platforms. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
10 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
11 2) Light-weight |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
12 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
13 C is also one of the most light weight languages making it a good choice here too. We leverage the native APIs on the platform to reduce the Dynamic Windows footprint. Only implementing our own widgets or functionality when the target platform has no native support. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
14 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
15 3) Native |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
16 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
17 While the C API hides all the internals for a platform from the developer behind typedefs and API calls, the native system functionality is just below the surface. Platform specific #ifdefs can allow you to use native system calls to augment Dynamic Windows functionality. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
18 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
19 This was a bit more simple in the past when all the system APIs were in C, but it is still possible with systems like Mac and iOS where the internals are in Objective-C, an intermediary source file may be necessary to call native code. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
20 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
21 4) Easily embeddable |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
22 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
23 The core Dynamic Windows functionality should be encapsulated into a single file when possible. The idea is that including Dynamic Windows in a project should be as simple as adding the dw.h header and the target platform core source file into your project. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
24 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
25 5) Simplicity |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
26 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
27 It should be fairly simple to write a modern and functional interface even when using a fairly low level language such as C. We accomplish this by encapsulating the complexity in the library behind a simple API. Using the box packing, signal handling and object data functionality that are the center pieces of the API. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
28 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
29 --- History --- |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
30 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
31 These principles were critical in the first Dynamic Window use case, it was used to write a graphical self-installer for OS/2 (and later, Windows and Unix). The executable header needed to be compact, and able to function with a minimal system install. Later scripting support was added using the built-in system scripting language REXX, which was also ported to the other platforms using Mark Hessling's Regina REXX interpreter. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
32 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
33 Dynamic Windows was then built as a Dynamic Link Library or Shared Object to be used in more standard applications, including my HandyFTP application which was originally written with the Cell Toolkit on OS/2, the graphical versions of the BitchX IRC client and various other private applications. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
34 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
35 In those early days not much thought was given to namespace pollution, or consistency for the internals, as long as the public APIs were exported and things compiled and worked things were good. As time marched on, code was acquired from other sources or contributed by people to the project and the internal naming got more and more random. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
36 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
37 At some point I became aware that on Linux, shared libraries basically exported all symbols by default, when I ran into an odd symbol conflict issue in an application I was working on. When built as DLLs on OS/2 and Windows this was not really an issue, since exports at the time were explicit in the export definition file. The experience on Linux however, made me think about the naming of global functions and variables, which caused me to start adding an underscore _ to any internal functions in an attempt to avoid conflicts. I did this on all platforms, since one of the design principles was embedding and in that use case even OS/2 and Windows can have name conflicts. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
38 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
39 When I came back from a break from working on Dynamic Windows, I started using _dw_ as the prefix to my internal functions, since while I have never actually run into an issue with an underscored function or variable colliding, it is possible that another library could be using underscores to do the same thing that we were. Therefore for visual consistency and as an added layer of protection the _dw_ prefix seemed like a good idea. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
40 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
41 During the 3.2 release cycle I have been effectively writing 3 new platforms simultaneously, one from scratch (Android) and two based on existing code (iOS based on Mac and GTK4 based on GTK3 and Mac). I began thinking about making things work and look the same on all the platforms. I tried to keep them all functioning similarly and in essentially the same style when possible, which is great for these new platforms but it caused them to diverge from the existing platforms. So I decided to go back and start updating the old existing platforms with the style choices I made with these new platforms, and it became obvious I should document and have discussions with users about these changes. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
42 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
43 --- Style in the 3.2 Release --- |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
44 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
45 - Public - |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
46 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
47 These functions, types and constants are part of the portable C API, usable by everyone on any platform. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
48 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
49 Function prefix: dw_ (lowercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
50 Handle type prefix: H (uppercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
51 Structure prefix: DW (mixedcase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
52 Constant prefix: DW_ (uppercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
53 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
54 - Internal - |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
55 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
56 These functions, variables and constants are used only inside Dynamic Windows, or the platform they are defined in. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
57 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
58 Funtion prefix: _dw_ (lowercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
59 Variable prefix: _dw_ (lowercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
60 Constant prefix: _DW_ (uppercase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
61 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
62 - Native - |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
63 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
64 These non-C classes (Objective-C or C++) or variables are platform specific and can be used inside a platform #ifdef |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
65 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
66 Class prefix: DW (mixedcase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
67 Variable prefix: DW (mixedcase) |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
68 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
69 There are at least two functions that are sort of exceptions to this, _dw_init_thread() and _dw_deinit_thread() are two internal functions that are exported for use in language bindings such as Google's Go. Plus at the time of this writing I have not finished the code audit, so there may be some that have not been changed yet to match this scheme or due to possible compatibility problems. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
70 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
71 Also the Kotlin code for Android does not follow this naming system, but to access the Kotlin APIs you need to call it via JNI, so there are no namespace issues. However it may make sense to have non-C code style guidelines added to this document at a later date. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
72 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
73 --- 3.2 Release C Coding Style Guidelines --- |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
74 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
75 Due to the base API being in C, it brings lots of compatibility but also many pitfalls. Writing applications in C brings memory handling and variable management pitfalls. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
76 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
77 We have tried to handle these issues by providing access to the C memory and string functions when including dw.h and providing a virtual method of storing data on window/widget handles with the dw_window_get_data() and dw_window_set_data() APIs. This allows you to avoid creating global variables, and instead save data on the window handles, along with macros for converting types such as: DW_POINTER_TO_INT() and DW_INT_TO_POINTER(). |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
78 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
79 Ideally globals should only be used for data that is truly global, settings and such. Windows and other handles should be context specific, created in dwmain() and then destroyed when leaving dw_main(). Any window specific data should be saved on the window handle with dw_window_set_data() then accessed with dw_window_get_data() in the callbacks using the window handles passed. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
80 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
81 The dwtest application should be updated in the future to adhere to these guidelines, but since it was originally written ages ago it is not an example of a modern Dynamic Windows application. Dynamic Windows Interface Builder should be looked at for modern Dynamic Windows coding style. |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
82 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
83 --- Contributing --- |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
84 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
85 This is a preliminary document subject to change, if you have any input on this document, such as suggestions or criticisms, I am posting it on the DBSoft forums and you can comment on it there: |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
86 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
87 https://dbsoft.org/forum/forumdisplay.php?fid=3 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
88 |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
89 Thanks for reading! |
7534466688da
Add preliminary style and design document for Dynamic Windows 3.2.
bsmith@81767d24-ef19-dc11-ae90-00e081727c95
parents:
diff
changeset
|
90 Brian |