Named Enumerations

[IdeasVacuum]

Hello Chaps

.... not looking for any other method or work-around, this is just about using Named Enumerations.

Why would we want Named Enumerations? Wouldn't the main reason be to allow constants to have the same value but without conflict?

When Named Enumerations were first introduced, I dabbled with them, could not really find a purpose and have not used them.
However, the app I'm currently working on is getting a bit verbose in the comments. I like to be able easily understand my own code a year later when a mod is required. So, replacing certain gadget Id arrays with constants that have meaningful names seems like a reason to use Named Enumerations. An experiment with that aim:

Code: Select all

Enumeration Window
#Win
#Panel
#FileIO
#Pack
#CntrFilesInOut
#TextFileIn
#TextFileOut
#CntrStrFin
#StrFileIn
#CntrStrFout
#StrFileOut
#BtnImgFileIn
#BtnImgFileOut
#CntrList
#TextList
#EditorList
#Font10R
EndEnumeration

Enumeration ImgContainer
#CntGdtImgList00
#CntGdtImgList01
#CntGdtImgList02
EndEnumeration

Enumeration ImgCanvas
#CnvGdtImgList00
#CnvGdtImgList01
#CnvGdtImgList02
EndEnumeration

Enumeration ImgTxtTitle
#TxtGdtImgList00
#TxtGdtImgList01
#TxtGdtImgList02
EndEnumeration

Enumeration ImgCheckBox
#ChkGdtImgList00
#ChkGdtImgList01
#ChkGdtImgList02
EndEnumeration

LoadFont(#Font10R, "Arial", 10, #PB_Font_HighQuality)
UsePNGImageDecoder()
Global igImgNImg.i = CatchImage(#PB_Any,?ImgN)

              If OpenWindow(#Win, 0, 0, 700, 650, "Named Enums", #PB_Window_SystemMenu | #PB_Window_ScreenCentered)

                                 iCntrW = 170
                                  iCnvW = (iCntrW - 10)
                                  iTxtW = (iCntrW - 30)
                                  iChkX = (iCntrW - 25)

                           ContainerGadget(#CntGdtImgList00,     5,      5, iCntrW, 150, #PB_Container_BorderLess)
                              CanvasGadget(#CnvGdtImgList00,     5,      5,  iCnvW, 120)
                                TextGadget(#TxtGdtImgList00,     5,    125,  iTxtW,  20, "")
                              CanvasGadget(#ChkGdtImgList00, iChkX,    125,     20,  20)
                        SetGadgetAttribute(#ChkGdtImgList00, #PB_Canvas_Image, ImageID(igImgNImg))
                            SetGadgetColor(#CntGdtImgList00, #PB_Gadget_BackColor, RGB(185,220,255))
                            SetGadgetColor(#TxtGdtImgList00, #PB_Gadget_BackColor, RGB(185,220,255))
                             SetGadgetFont(#TxtGdtImgList00, FontID(#Font10R))
                             SetGadgetData(#CntGdtImgList00, 0)
                             SetGadgetData(#CnvGdtImgList00, 0)
                           CloseGadgetList()

                           ContainerGadget(#CntGdtImgList01,     5,    160, iCntrW, 150, #PB_Container_BorderLess)
                              CanvasGadget(#CnvGdtImgList01,     5,      5,  iCnvW, 120)
                                TextGadget(#TxtGdtImgList01,     5,    125,  iTxtW,  20, "")
                              CanvasGadget(#ChkGdtImgList01, iChkX,    125,     20,  20)
                        SetGadgetAttribute(#ChkGdtImgList01, #PB_Canvas_Image, ImageID(igImgNImg))
                            SetGadgetColor(#CntGdtImgList01, #PB_Gadget_BackColor, RGB(185,220,255))
                            SetGadgetColor(#TxtGdtImgList01, #PB_Gadget_BackColor, RGB(185,220,255))
                             SetGadgetFont(#TxtGdtImgList01, FontID(#Font10R))
                             SetGadgetData(#CntGdtImgList01, 0)
                             SetGadgetData(#CnvGdtImgList01, 0)
                           CloseGadgetList()

                           ContainerGadget(#CntGdtImgList02,     5,    315, iCntrW, 150, #PB_Container_BorderLess)
                              CanvasGadget(#CnvGdtImgList02,     5,      5,  iCnvW, 120)
                                TextGadget(#TxtGdtImgList02,     5,    125,  iTxtW,  20, "")
                              CanvasGadget(#ChkGdtImgList02, iChkX,    125,     20,  20)
                        SetGadgetAttribute(#ChkGdtImgList02, #PB_Canvas_Image, ImageID(igImgNImg))
                            SetGadgetColor(#CntGdtImgList02, #PB_Gadget_BackColor, RGB(185,220,255))
                            SetGadgetColor(#TxtGdtImgList02, #PB_Gadget_BackColor, RGB(185,220,255))
                             SetGadgetFont(#TxtGdtImgList02, FontID(#Font10R))
                             SetGadgetData(#CntGdtImgList02, 0)
                             SetGadgetData(#CnvGdtImgList02, 0)
                           CloseGadgetList()
              EndIf

              Repeat
              Until WaitWindowEvent(1) = #PB_Event_CloseWindow


DataSection     ;ImgN
  ImgN:
    Data.q $0A1A0A0D474E5089,$524448490D000000,$1400000014000000,$1D898D0000000608,$475273010000000D
    Data.q $0000E91CCEAE0042,$0000414D41670400,$00000561FC0B8FB1,$0000735948700900,$1501C20E0000C20E
    Data.q $49EC010000804A28,$79DC634F38544144,$2A26022A067FFFE7,$2ECA063E8A36059A,$9860C2CEAAE0C19B
    Data.q $F4C85C3007B24FEE,$E30339576A8317FB,$1862F6C7420CBFDF,$D170620AC8379208,$D4516B1DF16300E2
    Data.q $CB0334E977C81860,$32BFDFCC45604F97,$FCF1C0D70C9A2DC8,$AED883269BB58331,$76B1827EBF4C0CF5
    Data.q $30C01812C8031245,$66667FC32A829BF0,$06C0903D398502B8,$7C7CE060728D326A,$F6E7E5CB2045C50F
    Data.q $1BC318B097F036E1,$D0623D9EAB846F07,$30C509CFD061C86C,$D79DD1C3079D8DEC,$6233D5C05467EE18
    Data.q $C0EA7959AF20874B,$E0614C2831720EBD,$0CF9CE95C33B1B1F,$345B18C331237C2F,$82D453B8659490FE
    Data.q $E6E7E19030C915B0,$28F874DE186AC76D,$7D86145FB9E1972E,$E23859DE191382CF,$FD89D0B613384E4C
    Data.q $5E946862575B120C,$66251638B7418735,$4EF0F85035611591,$8E4370944F24A306,$048D1C184B8DC979
    Data.q $DC9F38198ADBD419,$EFBC30291414B547,$A54063FCCFFFEBF4,$CCFFF2ED637E0A05,$C863B1B2FFFF1DFC
    Data.q $C19B8631D47ED481,$C5560F6566EC3300,$13FEBEEFFEF879BF,$F17FFF73A6D8E1AC,$FFFCCCC7FBA8A20B
    Data.q $7E5EE10370A3AAE4,$C501DCCEF0CC5C90,$E181B1985E6F20F9,$2196B3FC581B2B1F,$A4449E182F13C1C3
    Data.q $862E4E5FCE928031,$C2B2307C3257134B,$823F2F41B9410E9E,$42FCDF8626EF7441,$D8A31BC4AD26970C
    Data.q $882699C6C26B1AA2,$70438448794FA090,$5730F99DD100012A,$490000000047F152
    Data.b $45,$4E,$44,$AE,$42,$60,$82
EndDataSection

....but it doesn't work, it seems there is a conflict when Gadget constants have the same value, even though they are members of different Named Enumerations.

Is that a fault in my code or is it the case that Named Enumerations are not that useful?

[Josh]

Wouldn't the main reason be to allow constants to have the same value but without conflict?

How should that work? A constant with the value X is X, no matter how you create it. Why should it suddenly be possible to create two gadgets with the same gadget number?

Named enumerations are useful if you want to continue the gadget numbers in various include files.

Code: Select all

;IncludeFile 1
Enumeration Gadgets
  #Gad11
  #Gad12
  #Gad13
EndEnumeration

;InlcludeFile 2
Enumeration Gadgets
  #Gad21
  #Gad22
  #Gad23
EndEnumeration

[kenmo]

I think you're misunderstanding how to use Named Enums. You give Enums the SAME name if you want to avoid conflicts, not all DIFFERENT names.

The usual examples are "Windows", "Gadgets", "Events", etc because you don't want to double-use a Window number, or a Gadget number, or so on.


And by "avoid conflicts" I mean, not repeat a value. Ex: enums 0-5, 6-8, 9-30, 31-32 ...
You can't have two gadgets named #This and #That, if #This and #That are just names for the same number.

[IdeasVacuum]

Hi guys

Josh - nothing is 100% impossible, but of course I'm playing devils's advocate - the Help could be a lot better on the subject.

I just don't see the actual uses of Named Enumerations being so, well, useful, unless someone out there can think of a truly great one.

[Josh]

The hope dies last.
I still hope for my named enum wish for the Ide, which I wrote three years before we got named Enums in Pb

[TI-994A]

I just don't see the actual uses of Named Enumerations being so, well, useful, unless someone out there can think of a truly great one.

Code: Select all

;snippet 1
Enumeration
  #win1  ;0 
  #win2  ;1
  #win3  ;2
  #gad1  ;3
  #gad2  ;4
  #gad3  ;5
  #img1  ;6
  #img2  ;7
  #img3  ;8
  #fon1  ;9
  #fon2  ;10
  #fon3  ;11
EndEnumeration

Code: Select all

;snippet 2
Enumeration Windows
  #win1  ;0
  #win2  ;1
  #win3  ;2
EndEnumeration

Enumeration Gadgets
  #gad1  ;0
  #gad2  ;1
  #gad3  ;2
EndEnumeration

Enumeration Images
  #img1  ;0
  #img2  ;1
  #img3  ;2
EndEnumeration

Enumeration Fonts
  #fon1  ;0
  #fon2  ;1
  #fon3  ;2
EndEnumeration

PureBasic assigns and tracks object indexes sequentially, and maintains separate index tables for different objects. This means that a window, gadget, image, font, etc., could safely be assigned the same index numbers with no risk of clashing (as per the second code snippet).

Furthermore, if all objects were simply enumerated sequentially (as per the first code snippet), there would be gaps in their respective index tables. This would result in wasted resources as even the unused indexes are allocated.

The second code snippet efficiently references each object type from index 0, while the first snippet would result in 3 unused indexes in the gadgets table, six unused indexes in the images table, and 9 unused indexes in the fonts table. Negligible for small projects, but it would add up in UI-intensive and resource-rich applications.

> PureBasic Objects

[Josh]

@TI-994A
Your example also works with unnamed enums too . The real benefit of named Enums is if you want to continue the enumeration in another include file.

[TI-994A]

Your example also works without named enums too . The real benefit of named Enums is if you want to continue the enumeration in another include file.

True, although not just for included files, but also when further enumerations might be required later into the code.

Plus, it's simply good programming practice.

[IdeasVacuum]

Agree to disagree?

Continuing the enumeration in another include file, or later into the code, could be bad practice - isn't it better to have all your constants in one place, in the main file of your project (or a .pbi dedicated to constants)?

TI-994A - I think your clear description and example of Named Enumerations is exactly what we should see in the Help.

[skywalk]

Then, how do you make a standalone include files like math.pbi, strings.pbi, network.pbi, etc.?
Each of those have their own constants and structures.

[TI-994A]

Then, how do you make a standalone include files like math.pbi, strings.pbi, network.pbi, etc.?
Each of those have their own constants and structures.

Valid points. However, the risk of resource-overlaps exist only with object resources (ie: windows, gadgets, images, etc.) and not with mere constant values.

While named enumerations would address such issues efficiently, the possibility of including files that do not conform to such conventions are still very real, and could lead to unexpected clashes.

To avoid this altogether, the best practice would be to delegate the allocation and assignment of object resources to the compiler (ie: through the use of #PB_Any).

[TI-994A]

Agree to disagree?

Always!

[Josh]

The resources only affect the compiler during the compilation process. For the created exe it does not matter if you use a gadget number of 0, a gadget number of 100000 or #PB_Any.

[kenmo]

Some relevant parts from the PB Help

Code: Select all

  Enumeration Gadget
    #GadgetInfo ; will be 0
    #GadgetText ; will be 1
    #GadgetOK   ; will be 2
  EndEnumeration
  
  Enumeration Window
    #FirstWindow  ; will be 0
    #SecondWindow ; will be 1
  EndEnumeration

  Enumeration Gadget
    #GadgetCancel ; will be 3
    #GadgetImage  ; will be 4
    #GadgetSound  ; will be 5
  EndEnumeration

I. Indexed numbering

The static, indexed way, allows you to reference an object by a predefined numeric value. The first available index number is 0 and subsequent indexes are allocated sequentially. This means that if you use the number 0 and then the number 1000, 1001 indexes will be allocated and 999 (from 1 to 999) will be unused, which is not an efficient way to use indexed objects. If you need a more flexible method, use the dynamic way of allocating objects, as described in section II.

Overview of the different PureBasic objects

Different PureBasic objects (windows, gadgets, sprites, etc.) can use the same range of object numbers again. So the following objects can be enumerated each one starting at 0 (or other value) and PureBasic differs them by their type:
- Database
- Dialog
- Entity
- File
- FTP
- Gadget (including the ScintillaGadget())
- Gadget3D
- Image
- Library
- Light
- Mail
- Material
- Menu (not MenuItem(), as this is no object)
- Mesh
- Movie
- Music
- Network
- Node
- Particle
- RegularExpression
- SerialPort
- Sound
- Sound3D
- Sprite
- StatusBar
- Texture
- ToolBar
- Window
- Window3D
- XML

[Fred]

A named enumeration just declare an enumeration group which can be re-opened later when using the same name. It allows for example to have file like 'MainWindow.pb', 'FindWindow.pb', 'AboutWindow.pb' where each file contains its own definition of 'Enumeration Gadget', 'Enumeration Window', etc. You can include the file where you want in any order, it will always work as each enum will be treated as a single enum at the end. That's the main purpose of named enumeration. The name is not here to describe what you put in the enum . btw: I don't see any bad practice by splitting your enumeration across several include, as you usually group your code by logic (the Visual designer use this for example for each form).