Fix and improve CreateIconFromResource(Ex) and LookupIconIdFromDirectory(Ex) documentation - #2242
Open
Dimitriy Ryazantcev (DJm00n) wants to merge 2 commits into
Conversation
…from HTML to Markdown
|
Dimitriy Ryazantcev (@DJm00n) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. Jim Walker (@jwmsft) |
|
Dimitriy Ryazantcev (@DJm00n) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. Jim Walker (@jwmsft) |
…ory(Ex) documentation
CreateIconFromResourceEx:
- presbits: clarify the parameter accepts a single RT_ICON/RT_CURSOR image, not a
resource group directory; redirect buffer format details to Remarks
- fIcon: remove misplaced LOCALHEADER sentence (covered in the DIB format bullet in Remarks)
- cxDesired/cyDesired: clarify that zero without LR_DEFAULTSIZE uses the size stored in
presbits without scaling, rather than vaguely "the actual resource size"
- Flags: remove LR_SHARED — it does not produce sharing or caching for this function
and makes the handle impossible to destroy; remove from keyword metadata as well
- Remarks: replace boilerplate sentence with a proper description of the three accepted
buffer formats (DIB, PNG, ANI/RIFF-ACON); add ANI sizing and fIcon-ignored notes
CreateIconFromResource:
- presbits: redirect buffer format details to CreateIconFromResourceEx Remarks
- fIcon: remove misplaced LOCALHEADER sentence
- Remarks: remove boilerplate sentence; expand the wrapper description to explain the
LR_DEFAULTSIZE consequence (always default system size) and how to get a specific size
- Add Examples link
LookupIconIdFromDirectoryEx:
- Description: replace the size/color-depth summary with the actual scoring algorithm —
each candidate is scored by its departure from the target width, height, and color
depth, with the width and height terms doubled when the candidate is undersized and
the color-depth term always doubled; lowest score wins, ties broken by color depth
then directory order
- cxDesired/cyDesired: shortened to defer the zero-value behavior to the Flags entry;
corrected the false claim that zero size without LR_DEFAULTSIZE returns the first
directory entry — the scoring loop always runs, and at zero size the width/height
terms drop out for every candidate, so selection falls to color depth alone, only
degenerating to the first entry when all entries share the same color depth
- Flags table: consolidate the SM-metric substitution detail into the LR_DEFAULTSIZE
row as its single home; add the missing LR_DEFAULTSIZE entry; fix LR_MONOCHROME
description ("Searches for" rather than "Creates")
- Add LR_DEFAULTSIZE to keyword metadata
LookupIconIdFromDirectory:
- Description: clarify that this wrapper passes Flags=0 (not LR_DEFAULTSIZE), so size
does not take part in selection and the result is chosen by color depth as described
for LookupIconIdFromDirectoryEx, rather than unconditionally "the first entry"
Dimitriy Ryazantcev (DJm00n)
force-pushed
the
fix/createiconfromresource-input-format
branch
from
July 31, 2026 12:27
9c88e2b to
354ab67
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
CreateIconFromResourceEx:
resource group directory; redirect buffer format details to Remarks
presbits without scaling, rather than vaguely "the actual resource size"
and makes the handle impossible to destroy; remove from keyword metadata as well
buffer formats (DIB, PNG, ANI/RIFF-ACON); add ANI sizing and fIcon-ignored notes
CreateIconFromResource:
LR_DEFAULTSIZE consequence (always default system size) and how to get a specific size
LookupIconIdFromDirectoryEx:
set; without it, zero returns the first directory entry without size scoring
("Searches for" rather than "Creates")
LookupIconIdFromDirectory:
always returns the first directory entry without size scoring
Related: https://devblogs.microsoft.com/oldnewthing/?p=108925