WindowsResources

This page contains German notes about how the resource system works on Windows.

TODO: Translate and beautify this page.

References

• http://msdn.microsoft.com/en-us/library/ms632583.aspx (Menus and Other Resources)
• http://msdn.microsoft.com/en-us/library/aa380599.aspx (About Resource Files)
• http://msdn.microsoft.com/en-us/library/cc194804.aspx (Windows Resource Files)

Naming conventions

• http://msdn.microsoft.com/en-us/library/t2zechd4.aspx
• IDS_* refers to string resources
• IDI_* refers to icon resources
• IDB_* refers to bitmap resources
• IDC_* refers to cursor resources, but within a DIALOG resource (much more often used!) this also refers to dialog control resources
• IDD_* refers to dialog template resources
• IDR_* refers to other resource types (primarily menus, accelerators, ribbons)
• IDM_* is used within a menu resource to refer to menu items that do *NOT* use the MFC command architecture
• ID_* is used within a menu resource to refer to menu items that *DO* use the MFC command architecture

Valid ID ranges

• Jede Ressource wird innerhalb eines Moduls (.dll, .exe) durch eine eindeutige ID referenziert
• F¸r verschiedene Ressource-Typen gibt es unterschiedliche Bereiche, in denen die jeweilige ID liegen muss
• Details siehe http://msdn.microsoft.com/en-us/library/t2zechd4.aspx
• G¸ltige Nummern sind grunds‰tzlich 8 - 28671 (0x6FFF)
  • ID 0 ist nie erlaubt
  • ID 1-7 sind f¸r Standard Controls (z.B. IDOK, IDCANCEL) reserviert
  • IDs > 0x7FFF (32767) sind nie erlaubt
  • MFC reserviert die Nummern 0x7000 - 0x7FFF

Which resource types are there?

• Accelerator (Tastatur-Shortcuts)
• Dialog (Layout und Inhalte
• Icon (in den Grˆssen 16x16 und 32x32)
• Menu (Hauptmen¸ und Popup-Men¸s)
• String (z.B. Fehlermeldungs-Texte)
• Toolbar
• Version (Programmbeschreibung, Versionsnummer, Sprache, etc.)
• Bitmap (.bmp Files)
• Video (.avi Files)
• Registry Fragmente (.rgs Files)
• Beliebige Daten (Type RCDATA innerhalb des .rc Files)

.rc files

• .rc Files sind eigentlich Textfiles, die die Ressourcen eines Projekts beschreiben
• Ein .rc File kann mit #include andere Resource Files inkludieren (nicht beschr‰nkt auf .rc Files). Details siehe
  • http://msdn.microsoft.com/en-us/library/6t3612sk.aspx (TN035: Using Multiple Resource Files and Header Files with Visual C++)
  • http://msdn.microsoft.com/en-us/library/6e7446zd.aspx (How to: Include Resources at Compile Time)
• Diese kˆnnen aus dem gleichen Projekt, einem anderen Projekt, oder dem System (z.B. MFC) stammen
• Ueblicherweise wird auch resource.h inkludiert; dies ist ein File mit #define Anweisungen, um die numerischen Resource IDs auf Namen zu mappen
• Ueblicherweise werden .rc Files vom Resource-Editor, der Teil der IDE ist, automatisch verwaltet, d.h. man nimmt keine manuellen Aenderungen vor
• Tats‰chlich verwendet der Resource-Editor nicht direkt das .rc File, sondern ein vorg‰ngig daraus kompiliertes .aps File
• Bei Aenderungen wird das .rc File komplett neu generiert
  • Dadurch gehen z.B. Kommentare verloren, da diese schon bei der Umwandlung .rc -> .aps wegfallen

.rc2 files

• Die Konvention ist, dass ein Resource-File, welches manuell editiert werden muss, die Endung .rc2 tr‰gt
• Das .rc2 File wird dann im Haupt-Resource File (welches automatisch vom Resource-Editor verwaltet wird) included

TEXTINCLUDE resources

• Dieser Resource Typ dient allein dazu, die Informationen abzulegen, die im "Resource Includes" Dialog verwaltet werden
• Es gibt 3 Resourcen dieses Typs, entsprechend den 3 Abschnitten im "Resource Includes" Dialog
• Der Inhalt dieser Resourcen hat *KEINEN* Einfluss auf das Kompilieren oder Editieren des Resource Files

"Resource Includes" dialog

• Der "Resource Includes" Dialog kann so aufgerufen werden:

           Resource View > Resource File selektieren > Kontextmen¸ > Resource Includes

• Symbol Header File
  • Hier tr‰gt man den blanken Filenamen ein (¸blicherweise "resource.h")
  • Daraus wird die TEXTINCLUDE Resource mit ID 1 generiert
  • Es wird ebenfalls ein #include Statement ganz am Anfang des .rc Files generiert
• Read-only symbol directives
  • Hier tr‰gt man #include Statements ein, die auf weitere Header Files verweisen, die zus‰tzliche Resource IDs definieren
  • Diese Header Files sind read-only in dem Sinn, dass der Resource Editor nicht versucht, die Resource ID aus dem Header File zu entfernen, wenn die entsprechende Resource aus dem .rc File gelˆscht wird
  • Ueblicherweise tr‰gt man hier z.B. das MFC Resource Header File afxres.h ein
  • Aus allen Eintr‰gen in diesem Bereich wird die TEXTINCLUDE Resource mit ID 2 generiert
  • Die #include Statements werden ebenfalls weit oben im .rc Files eingetragen
• Compile-time directives
  • Hier tr‰gt man #include Statements ein, die auf weitere .rc Files verweisen, die zur Compile Zeit mt dem Haupt .rc File gemerged werden sollen
  • Die .rc Files sind nicht editierbar und tauchen nicht im Resource Editor auf
  • Aus allen Eintr‰gen in diesem Bereich wird die TEXTINCLUDE Resource mit ID 3 generiert
  • Die #include Statements werden ganz unten im .rc Files eingetragen und mit "#ifndef APSTUDIO_INVOKED" versehen

Loading resources

• http://msdn.microsoft.com/en-us/library/ms648006.aspx
• Es gibt diverse Mˆglichkeiten, um eine Ressource zu laden
  • Allgemeing¸ltige Funktionen: FindResource() und LoadResource()
  • Funktionen, die spezifisch f¸r einen bestimmten Ressourcen-Typ sind: LoadString(), LoadMenu(), etc.
  • MAKEINTRESOURCE Macro
• Allen Funktionen gemeinsam ist, dass sie wissen m¸ssen, *woher* sie die Ressource laden m¸ssen
• LoadString() und Co. benˆtigen dazu ein Module Handle (HINSTANCE)
  • Ein HINSTANCE Module Handle wird mit AfxGetInstanceHandle() bestimmt
  • Offenbar kˆnnen HMODULE Module Handles, die von LoadLibrary() zur¸ckgegeben werden, ebenfalls als HINSTANCE eingesetzt werden
• FindResource() und LoadResource() benˆtigen ein Module Handle (HMODULE)
  • Ein HMODULE Module Handle wird z.B. von LoadLibrary() zur¸ckgegeben; anstelle von HMODULE kann aber auch HINSTANCE verwendet werden
  • FindResource() gibt ein HRSRC zur¸ck, ein Handle auf den "Information Block" der gesuchten Ressource
  • Das HRSRC Handle kann dann an LoadResource() ¸bergeben werden - d.h. HRSRC ist auch ein HMODULE
  • LoadResource() gibt ein HGLOBAL Resource Handle zur¸ck, welches eine Art Pointer auf die bin‰ren Daten der Resource sind
  • Normalerweise wird mit den Ressourcen-spezifischen Funktionen gearbeitet und nicht mit LoadResource()
• Die meisten Ressourcen, die geladen wurden, m¸ssen auch wieder freigegeben werden (z.B. DestroyMenu()); die Ausnahme sind Strings
• Handles auf Module mit Ressourcen kˆnnen auch mit den folgenden globalen Funktionen managed werden
  • AfxFindResourceHandle(LPCTSTR lpszName, LPCTSTR lpszType) - gibt das HINSTANCE Handle zur¸ck, das die beschriebene Ressource enth‰lt
  • AfxGetResourceHandle() - gibt das HINSTANCE Handle zur¸ck, von dem Ressourcen per Default geladen werden sollen
  • AfxSetResourceHandle() - setzt ebendieses HINSTANCE Handle
• Das mit AfxSetResourceHandle() gesetzte Handle wird vermutlich in den Module State geschrieben