Icons and Images in Wisej.NET

Icons and Images in Wisej.NET, Module 1. Wisej.NET offers several ways to put a picture on a control, so the first decision in this course is always which mechanism owns the image.

The Image property holds a System.Drawing.Image that the server keeps in memory and sends to the browser as PNG. ImageSource holds only a string, so nothing is decoded on the server at all. Both fill the same visual slot on the control, which is exactly why the choice has to be deliberate.

That string can be a relative URL, an absolute URL, a named theme image or a resource.wx path, and the client resolves it. Image-capable controls share one contract through IImage, so a button, a label and a grid cell all expose the same family of image properties.

In IconDesk, the Open button takes an image object the server reads from a file. The Save button takes a theme image name on ImageSource. Print and Delete share a single ImageList and select their artwork by key, so the list decides what those two buttons draw.

An ImageList is indirection rather than storage. A key carries meaning that survives reordering, while an index is only a position and quietly points at different artwork once the collection changes. Replace the image stored under a key and every control using that key follows, with no other code touched.

The diagnostics label asks each button, through IImage, which image property is actually populated. That question catches a common defect: an image source assigned after an image key takes the slot, the key stays set, and the control draws the string instead. Reading the control beats guessing.

Running the page, four icons arrive by four different routes and all look equally correct. Only the Open button made the server decode a picture; the other three were resolved by the browser. The label names the mechanism behind each one, so the difference is visible rather than assumed.

Replacing the artwork behind the delete key updates that button on its own, because the control refers to the key and not to the picture. Assigning an image source to the same button afterwards changes what it draws while the key remains set and ignored.

Lab one: build the IconDesk command panel with all three mechanisms, add the diagnostics label that reads each button through IImage, and record what the key swap and the double assignment actually did.

Module 2. The ImageLab page in IconDesk puts an image object and an image-source string side by side on PictureBox controls, so the difference between the two pipelines becomes something you can see.

Asking which formats Wisej.NET supports has no single answer, and treating it as one causes real defects. A logo stretched out of proportion, a page that stalls while a remote photograph downloads, and an icon file that refuses to load all come from collapsing two format lists into one.

Keep the lists apart. Bitmap, metafile, icon, JPEG, GIF and PNG travel through System.Drawing and the Image property. The resource handler and theme images accept JPEG, PNG, GIF, SVG and bitmap as strings. SVG belongs to the string pipeline; it is not a System.Drawing format.

Six size modes describe what happens when the picture and the box disagree. Normal clips, AutoSize resizes the box to the picture, CenterImage centres it, StretchImage distorts it, Zoom fits the whole image inside, and Cover fills the box and crops the overflow.

Four controls share one source string and differ only by size mode, which isolates the sizing decision from the loading decision. The legacy icon file moves off the image-source string and onto the Image property, because icon and metafile belong to the System.Drawing pipeline.

LoadAsync fetches the partner photograph without holding the page while it arrives. One vector icon, addressed as a resource string, feeds four different sizes from the same asset. A report handler then prints, for every PictureBox, whether the picture came from Image or from ImageSource.

Running it, the same asset is clipped by Normal, fitted by Zoom, cropped by Cover and flattened by StretchImage. The remote photograph is still on its way, and the page stays usable while it downloads, which is the whole point of loading it asynchronously.

The vector row stays crisp at sixteen, twenty-four, thirty-two and forty-eight pixels. The small bitmap is already soft at thirty-two, because the browser is enlarging pixels that were never there. The report then names the pipeline behind each control, so nobody has to guess.

Lab two: build ImageLab with four size modes on one raster asset, a remote photograph through LoadAsync, one vector icon at four sizes, the report handler, and the format note.

Icons and Images, Module 3. The image on a control is often not a file you ship beside the page, but a source string, and the IconGallery screen fills five slots five different ways.

Module 2 left IconDesk with a typed path for every look, which is fine until the look has to change. A theme can supply the picture as a relative URL, an absolute URL or embedded data, or as a named image, and only the named image adds a layer of indirection.

Assigning a theme image name to ImageSource opens no file and creates no System.Drawing.Image. The name is a key the client resolves from the theme it has already loaded, which is why a different theme can supply different artwork without any change to your C# code.

The design-time Image Selector browses project images, theme images and every icon pack the project references, with a preview of each one. For monochrome icons it also previews the colour, so a recolouring decision is made by looking rather than by rebuilding and refreshing.

Read what the picker wrote. Designer.cs holds a resource source string that points back at the assembly holding the artwork, never a copy of the file itself. The same string can be computed at runtime, which matters when the icon depends on state rather than on layout.

Adding the colour suffix to a source string recolours a suitable monochrome vector icon. A literal colour works, but a theme colour name is better, because the icon then follows the theme instead of pinning one value that a future palette change will quietly contradict.

Running IconGallery, five slots are filled by a theme key, a relative URL, an absolute URL, a pack resource and a recoloured vector icon. They look equally settled, yet only the absolute URL depends on a host you do not control, and that is worth knowing before deployment.

Now switch themes. The theme key resolves to new artwork, and the theme colour named in the suffix changes with it. The three sources that named exact artwork stay identical, which is the practical difference between a semantic reference and a literal one.

Lab three: fill IconGallery through the Image Selector, recolour one monochrome icon with a theme colour name, read the strings in Designer.cs, and write the theme-switch note.

Module 4. IconDesk needs five icons today and perhaps forty more this quarter. Collecting them file by file gives you several stroke weights, no shared style and no record of where anything came from.

An icon pack is an ordinary .NET assembly whose artwork is stored as embedded resources. One file in the output folder can carry hundreds or thousands of icons, and each one stays individually addressable through the resource handler, so nothing is bundled into a single unusable blob.

The two mechanisms deliver differently, and that decides where each belongs. Pack icons are pulled: one request the first time an icon is used, then the browser cache. Theme images are pushed, preloaded together with the theme, which is why very large catalogues belong in a pack.

Install the packs from the official Wisej-4 packages and keep their major versions aligned with the framework. Then build the project before looking for them, because the image explorer lists only the packs the project has actually compiled against.

Pick an icon and read what the designer generated: the resource handler, the pack assembly, the icon file, and optionally the colour suffix. Every part of that string is checked at run time, which is why a filename typed from memory resolves to nothing at all.

In C#, prefer the pack's icon catalogue over a hand-written string, so a rename becomes a compiler error instead of a blank control. The exact namespace varies from pack to pack. Set one image property per control, and keep a caption beside any icon that carries meaning.

The IconCompare page shows the same five concepts drawn by two families, which makes the stylistic difference obvious in a way a catalogue page never does. Two monochrome icons accept the colour suffix with a theme colour name; multi-colour artwork simply ignores it.

The network panel supplies the evidence: one request per icon on the first load, and cache hits on the reload. A recommendation backed by that is defensible, and it also shows why referencing a large pack does not cost the learner a large download.

Lab four: reference two Wisej-4 packs, build an IconCompare page from both, pick at least five icons in the explorer, recolour two, and name the project's primary icon family.

Icons and Images, Module 5. Five IconDesk assets stop being loose files beside the application and start shipping inside the assembly, addressed by a string instead of by a path on disk.

Artwork deployed next to the application is one missed copy step away from broken. The server answers with a not-found, the control draws nothing, and the file is still present on the developer's machine, which is why the problem usually survives until somebody else runs the build.

There is no API for this. Add the file to the project and set its build action to Embedded Resource, and the bytes move into the assembly manifest. That single property is also what turns an ordinary class library into an icon pack, as Module 6 will show.

Address the resource as a string. Without an assembly name, Wisej.NET searches the loaded assemblies for a matching resource. Naming the assembly explicitly, written without the file extension, removes the ambiguity when two assemblies could each contain a file with the same name.

The handler serves exactly nine extensions: stylesheets, scripts, HTML, JPEG in both spellings, PNG, GIF, vector graphics and bitmaps. Nothing else is served, so an icon file embedded with high hopes is still a not-found, and the fix is converting it rather than debugging the URL.

A file deployed with the application can answer the same address before the embedded copy does. That is genuinely useful for a customer re-brand or an urgent fix with no rebuild, and it also means the folder holding those overrides is now something you have to protect.

In the browser, five requests return five successful responses, all served out of the application assembly, and the reload comes from the cache instead. The vector artwork stays markup the whole way through; at no point does it become a System.Drawing image.

Dropping a replacement logo beside the deployed application changes the picture with no rebuild at all. Then one doubled letter in a resource name produces a not-found, and the six-step checklist finds it at step four, which is faster than reading the code again.

Lab five: embed five assets, show them all on ResourceLab, qualify one source with the assembly name, override one with a deployed file, and write up the not-found hunt.

Module 6. IconDesk now uses icons everywhere and owns none of them. The remedy is a pack of its own: a class library, a Resources directory, and twelve vector icons marked as embedded resources.

At the moment the same icon is spelled four slightly different ways across four screens. Every one of those paths is a string, so three of them compile perfectly and fail only in the browser, which moves the mistake from the build to a customer's screen.

The documented recipe has four steps: create a class library, create a Resources directory, put the icons in it, and set their build action to Embedded Resource. What comes out is one address made of the handler, the assembly name and the resource path. Confirm it once against the running application.

The catalogue turns that address into IntelliSense. One private constant holds the shared part of the path, and one public constant per icon names the concept rather than the file, so callers write a product name like Save or Warning instead of repeating a path.

Two routes end at the same string. The Image Selector writes it into Designer.cs when a layout decision picks the icon, and runtime code reads it from the catalogue when application state decides. And the vector artwork is still markup the client resolves, never a System.Drawing image.

It runs. Twelve icons come from one referenced assembly, arriving one request at a time as each is first used, and served from the browser cache on the next load. Nothing in the application needed to know where on disk the artwork lives.

The colour suffix recolours two icons and is ignored by the third, because that file has a colour hard-coded into the artwork. Strip the hard-coded value from the markup, then check the result again in a dark theme rather than assuming the fix carried over.

Three habits keep the pack maintainable: one concept per icon, the catalogue treated as the pack's public API so renaming stays a compiler concern, and a documented override path for an application that needs different artwork under the same familiar name.

Lab six: build the IconDesk.Icons library with twelve embedded icons and the catalogue, assign some in the designer and some from code, check three recolours, and write the versioning rules.

Icons and Images in Wisej.NET, Module 7, the capstone. IconDesk can already draw an icon five different ways. Now it gains a sixth, and more importantly the written rule that decides between them.

An image object, an image-source string, a theme image, an embedded resource, and now an icon font. Six mechanisms with no written first choice is how the same Delete command ends up looking different on three screens of the same application.

An icon font skips the image pipeline entirely. One stylesheet link in the application's Default.html lets the browser fetch the CSS and the font files, and a CSS class placed inside text on a control that allows HTML draws the glyph as a character.

Neither approach wins outright. Wisej resources bring recolouring, the image selector and real image properties. Fonts bring an existing CSS design system and let a glyph sit inline with text. Whether that stylesheet comes from a public network or your own server is a genuine decision.

In code the two decisions sit at different levels. The stylesheet link is a page-wide decision; allowing HTML is a per-control decision you make deliberately. Two glyphs carrying different roles can then share one grid cell, and the click reports which element was actually hit.

Here is the policy. Theme images for semantic, theme-following artwork. One primary pack for commands. The custom pack for product artwork you own. Raster formats for photographs. Icon fonts only where the HTML integration genuinely pays for the extra dependency.

The summary page runs all five mechanisms at once. Switch the theme and only the theme image and the recoloured vector icon follow it. The pack icon, the custom-pack icon and the embedded asset stay exactly as drawn, which is the behaviour the policy is written around.

The action column answers two different clicks from a single cell by reading the role of the element that was hit. The quality pass then repeats in a dark theme, checking that every glyph is still readable and every action still carries a name a screen reader can announce.

The capstone: the stylesheet and one toolbar that allows HTML, the role-aware grid column, the summary page covering five mechanisms, the written icon policy, and a light and dark quality note.