Introduction

The purpose of this section is to describe the behaviour, creation, and handling of objects in PureBasic. For the demonstration, we will use the Image object, but the same logic applies to all other PureBasic objects. When creating an Image object, we can do it in two ways: indexed and dynamic.

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. The indexed way offers several advantages:

- Easier handling, since no variables or arrays are required.
- 'Group' processing, without the need to use an intermediate array.
- Use the object in procedures without declaring anything in global (if using a constant or a number).
- An object that is associated with an index is automatically freed when re-using that index.

The maximum index number is limited to an upper bound, depending of the object type (usually from 5000 to 60000). Enumerations are strongly recommended if you plan to use sequential contants to identify your objects (which is also recommended).

Example:

  CreateImage(0, 640, 480) ; Create an image, the n°0
  ResizeImage(0, 320, 240) ; Resize the n°0 image

Example:

  CreateImage(2, 640, 480) ; Create an image, the n°2
  ResizeImage(2, 320, 240) ; Resize the n°2 image
  CreateImage(2, 800, 800) ; Create a new image in the n°2 index, the old one is automatically free'ed

Example:

  For k = 0 To 9
    CreateImage(k, 640, 480) ; Create 10 differents images, numbered from 0 to 9
    ResizeImage(k, 320, 240) ; Create a new image in the n°2 index, the old one is automatically free'ed
  Next

Example:

  #ImageBackground = 0
  #ImageButton     = 1

  CreateImage(#ImageBackground, 640, 480) ; Create an image (n°0)
  ResizeImage(#ImageBackground, 320, 240) ; Resize the background image
  CreateImage(#ImageButton    , 800, 800) ; Create an image (n°1)

II. Dynamic numbering

Sometimes, indexed numbering isn't very handy to handle dynamic situations where we need to deal with an unknown number of objects. PureBasic provides an easy and complementary way to create objects in a dynamic manner. Both methods (indexed and dynamic) can be used together at the same time without any conflict. To create a dynamic object, you just have to specify the #PB_Any constant instead of the indexed number, and the dynamic number will be returned as result of the function. Then just use this number with the other object functions in the place where you would use an indexed number. This way of object handling can be very useful when used in combination with a linked list, which is also a dynamic way of storage. A complete example of dynamic objects and linked lists can be found here: MDI ImageViewer.pb.

Example:

  DynamicImage1 = CreateImage(#PB_Any, 640, 480) ; Create a dynamic image
  ResizeImage(DynamicImage1, 320, 240) ; Resize the DynamicImage1