Device Contexts and GDI objects in the LCL interfaces: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 2 | - | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 8 | - | ||
| 9 | - | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 13 | - | ||
| 14 | 1 | ## Warning and overview | |
| 15 | 2 | ||
| 16 | - | ||
| 3 | + | This page is about the graphic Handle objects of the LCL interfaces: **Device contexts** (alias DC, canvas handles) and **GDI objects** (alias font handles, pen handles, brush handles, bitmap handles, palette handles, region handles). | |
| 17 | 4 | ||
| 18 | - | ||
| 5 | + | The TCanvas, TFont, TBrush, TPen use them too and handle all the bookkeeping automatically. So, it is better and often faster to use the LCL classes instead of the LCL interface handles. | |
| 19 | 6 | ||
| 20 | - | ||
| 7 | + | The LCL interfaces work all different here, especially if you use these functions not like TCanvas, TFont, TPen, TBrush and TBitmap do. If you miss a function, please ask first on the mailing list, before trying these functions. | |
| 21 | 8 | ||
| 22 | 9 | ## Why are TFont, TPen, TBrush faster than accessing the LCL interfaces directly? | |
| 23 | 10 | ||
| 24 | - | ||
| 25 | - | ||
| 11 | + | - They use resource caches. This means if you allocate a font with the same attributes a second time, it will reuse the handle. These caches work global. So, even if you free a TFont, the handle is still in the cache and can be used if you create a TFont with the same attributes. | |
| 12 | + | - The LCL interfaces are tested and optimized for these objects. | |
| 26 | 13 | ||
| 27 | - | ||
| 14 | + | Probably you will only get more speed by accessing directly the interfaces (the gtk, the winapi, the qt, ...). | |
| 28 | 15 | ||
| 29 | - | ||
| 16 | + | The only reason to access the LCL interfaces is to quickly port some 'optimized' Delphi code. | |
| 30 | 17 | ||
| 31 | 18 | ## Device Context | |
| 32 | 19 | ||
| 33 | - | ||
| 20 | + | Normally a Device Context (DC) is a handle (=LCL interface object) to draw on a TWinControl handle. A TCanvas.Handle is a DC. | |
| 34 | 21 | ||
| 35 | 22 | ## GetDC | |
| 36 | 23 | ||
| 37 | - | ||
| 24 | + | For delphi compatibility the parameter 0 creates a DC for the current screen with some default values. Otherwise it creates a DC for the given TWinControl handle. The LCL interface provides default GDI objects (font, pen, brush, region, palette and bitmap). The current GDI objects can be changed with SelectObject and should be restored before releasing the DC, either with SelectObject or RestoreDC. Otherwise the DeleteObject can fail, which can create mem leaks. | |
| 38 | 25 | ||
| 39 | 26 | ## ReleaseDC | |
| 40 | 27 | ||
| 41 | - | ||
| 28 | + | This frees the DC. It is allowed to release a DC, where the default GDI objects have not been restored. The LCL interface will now free the default GDI objects of the DC. If the application selected the default GDI objects of a DC1 in another DC2 and frees DC1 - which is a bug in the application - the behavior depends on the LCL interface. The winapi interface uses global stock objects and will ignore the error. The gtk interface will raise an exception. | |
| 42 | 29 | ||
| 43 | 30 | ## CreateFontIndirectEx | |
| 44 | 31 | ||
| 45 | 32 | ## SelectObject | |
| 46 | 33 | ||
| 47 | - | ||
| 48 | - | ||
| 34 | + | This replaces a GDI object in a DC and returns the old GDI object. You can select a GDI object in any number of DC at the same time. The application should unselect the GDI object before calling DeleteObject. For example: | |
| 35 | + | ||
| 36 | + | ``` pascal | |
| 49 | 37 | FontHandle1:=CreateFontIndirect...; | |
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 38 | + | OldFontHandle:=HFONT(SelectObject(aDC,FontHandle1)); | |
| 39 | + | ... some text operations ... | |
| 40 | + | SelectObject(aDC,OldFontHandle); | |
| 41 | + | DeleteObject(FontHandle1); | |
| 54 | 42 | ``` | |
| 55 | 43 | ||
| 56 | - | ||
| 57 | - | ||
| 58 | 44 | ## DeleteObject | |
| 59 | 45 | ||
| 60 | - | ||
| 46 | + | This frees a GDI object. If a GDI object is freed, that is still selected in a DC, it fails and returns 0. This means every LCL interface must bookkeep if a GDI object is selected in a DC. | |
| 61 | 47 | ||
| 62 | 48 | ## SaveDC | |
| 63 | 49 | ||
| 64 | - | ||
| 50 | + | This saves the current state of a DC to an internal stack. The references to the GDI objects are stored, not their values. See below RestoreDC. | |
| 65 | 51 | ||
| 66 | 52 | ## RestoreDC | |
| 67 | 53 | ||
| 68 | - | ||
| 54 | + | This loads a state from the internal DC stack. It undoes all SelectObject calls. Although the winapi supports restoring several states at once, most LCL interfaces will not support this. | |
| 69 | 55 | ||
| 70 | - | ||
| 71 | - | ||
| 56 | + | Example: | |
| 57 | + | ||
| 58 | + | ``` pascal | |
| 72 | 59 | Font:=CreateFontIndirect...; | |
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 76 | - | ||
| 60 | + | DCIndex:=SaveDC(DC); | |
| 61 | + | SelectObject(DC,Font); | |
| 62 | + | RestoreDC(DCIndex); | |
| 63 | + | DeleteObject(Font); | |
| 77 | 64 | ``` | |
| 78 | 65 | ||
| 79 | 66 | --- | |
| 80 | - | ||
| 67 | + | *From the Free Pascal wiki, page "Device Contexts and GDI objects in the LCL interfaces", as it stood on 2020-02-13 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 68 | + | Category: Graphics | |
| 69 | + | Category: LCL |