Here it is [finally]! As mentioned in the ZeldaShark post, ZeldaGrabber is a utility designed to take screen grabs of Zelda Classic screens. Players can keep track of/"map" their own progress in a game, or you map builders can easily create maps of your own quests for previews, teasers, or what-have-you.
Here's an example export image with background. (I just grabbed the first image I saw and kept it cause the girls are looking at the map like they're surprised) Anybody know how to resize this?
ZeldaGrabber 1.5 works in Windows XP through Windows 7 (supposedly it won't in W8 or later; this limitation will likely be removed in future versions).
I tried to make using it as intuitive as possible, but there's quite a few functions, so I'll try to write a help guide here.
Newest Version: 1.6
ZeldaGrabber 1.6 Setup (Mediafire)
Main Screen - Controls
ZG supports working on multiple files at once; it's just not an average MDI-style application. So, at the upper left is the dropdown to switch between maps (keyboard shortcut: Ctrl+Tab/Ctrl+Shift+Tab).
To the right of it is the toolbar. Hovering over buttons with the mouse will show you their names and their keyboard shortcuts.
- New Map... (Ctrl+N) - Opens a dialog for you to set the properties of a new blank map. Select the title, number of screens wide and high (there's a limit of 32x32 in this version) and the dimensions of those screens. There are buttons to set the dimensions to percentages of the capture area. For example, you might capture a screen at 512x336 pixels in a 640x480 ZC window, but just want to use 256x168 for output so the entire map is a more reasonable size. When you're done, click OK to start working with it.
- Open Map... (Ctrl+O) - Opens the familiar load file dialog. ZeldaGrabber has its own custom .zcmap work files, and you can open jpg/png/tiff images to import (more on that later). Clicking the dropdown arrow beside the button opens a recently-used file list (more recent towards the bottom).
- Feature: you can drag and drop files onto the window to open them, including .zcmaps and most images. The .zcmap file format is associated with the program upon install (and will get removed during uninstall). You can also pass a file's full path as a command line parameter.
- Close Map - Pretty self-explanatory. If there are changes to the current map, it will prompt you to save before closing.
- Save Map (Ctrl+S) / Save Map As... (Shift+Ctrl+S) - Saves the map in a custom format (.zcmap) that stores all the captured screens for easier editing later. Remember, this is distinct from Exporting. If the saved file does not already exist, clicking the button will open a standard Save dialog box for you to select the filename. Otherwise, it will just save the changes to disk with the last-used filename for that map. Click the arrow to get a menu which has Save As... to save under a new name.
- Export Map (Ctrl+E) - Opens a save dialog so you can Export the map in a common image format. BMP, GIF, JPG, PNG, and TIFF are supported currently. GIF, of course, will only save in 256 colors (the error diffusion is decent, but obviously I wouldn't recommend it), and JPG is lossy (but 90+ quality is quite good). JPG and TIFF have export options you can select; a small dialog will pop up after clicking Save to set them. (Bizarrely, different versions of Windows have different allowable options that may or may not work - I don't have an easy way to tell, but the dialog will try to help you with tips. Nothing bad will happen if you choose an unacceptable one, just an error dialog...and you'll have to try again.)
- Copy Screens (Ctrl+C) - Copy the selected screens on the map to an internal clipboard (that is, in this program only; it won't affect the normal Windows clipboard). You can then paste these screens, in the same alignment, onto another map (or the same map, too - just left click an unselected area to clear the selection first).
- Paste Screen (Ctrl+V) - Paste copied screens into the current map. Pasting is a two-step process: when first pasting, you will see the outline of the screens' area show up; they will appear in the same positions they were on in the map from which they were copied. You can now move this outline around to a different target area. When it is where you want the screens pasted, hit the Enter key and they will be placed on the map as well as added to this map's Captured Screens. If there are existing screens on the map "under" the pasted area, they will be removed from the map and will show as "not set" in the Captured Screens. Note: If the dimensions of your copied screens (for example, 10 screens wide by 4 screens high) are larger than the map they're being pasted into (like an 8x8 screen map), the program will disallow it, and tell you to select a smaller area.
- Undo (Ctrl+Z) - Undo the last action taken on this map. Things like map saving/exporting, and selecting/unselecting screens (without actually changing the map) are not undo-able. You can see what is in the Undo History list above the Captured Screens list. There are up to 10 levels of undo for each map. Beyond that number, the older actions will "roll off". Just about everything is undo-able, so go for it.
- Redo (Shift+Ctrl+Z) - Redo the last Undo action. In the Undo History list, the arrow will point to which step you are on; black text above the arrow are things that can be undone, and gray text below are things you can redo. As you would expect, if you undo some steps, and then change the map, the redo chain will be broken after that point, and you start a new undo sequence.
- NEW Touch-up Mode (Ctrl+T) - See description near top of this post ^
- Settings... - Open the Settings dialog. See below.
- About... - Open the About dialog.
Below the toolbar, on the left, is the Undo History list. It keeps track of your edits to the current map. It's not interactive in this program version; it's just for visual reference (to fill dialog space, really 
). Step through the list with the Undo and Redo buttons or their keyboard shortcuts.
Right of that is the Map Move buttons. These shift every screen on the map in the clicked direction. Screens that pass the edges of the map will wrap around to the opposite side. Good for scooting your map-in-progress over when you realize you've started at the wrong position. (Undo-able)
The rightmost controls are for changing the Map Area. If you need a larger map area than what you started with (or vice versa) then just type in the new dimensions of the map in screens, pick an Anchor Point to position the old map in the new area, and click Update. If placed screens on the current map would be off the boundaries of the new map area, they will be removed and will show in the Captured Screens as 'not set'. To grok how the anchor point works, imagine you were working with maps on paper, and you placed the new sheet of paper (area) over the existing paper (area) to trace the existing map onto the new. The anchor point is where you would put a pushpin to keep the two maps aligned while you were tracing. (Yep, also undo-able.)
Main Screen - Captured Screens
The Captured Screens list keeps track of all the associated screens (screenshots) for each map, whether they're "placed" (have a position set on the map) or "not set". When you hit the Hot Key to capture a screen, it will appear in the list. A counter above the upper-right corner keeps track of how many screens you have associated with the current map. An important usage note: when you first capture a screen, its status will be "not set" since it's not yet been placed on the map. But it's not just 'not set' for this map -- if you have other maps opened, you can switch to them and the screen will also be in their Captured Screens list. This is for the cases you're mapping an overworld and a dungeon at the same time -- you don't have to worry if the map you want the screen to go on isn't the current one. This screen will keep its special "any map" visibility until you first place it on one. After that, it's permanently associated with that map. (This is to keep the undo functionality from going insane. But don't worry, there is still a way to get it to any other screen.)
Right-clicking on any screen in the list will display a popup menu with a few choices:
- Copy to Clipboard - This uses the Windows clipboard to copy the image of this screen, so you can paste it in your favorite image editor and work with it.
- Copy to Map - This will duplicate the screen and add it to the Captured Screens list of any other map that's open. Opened maps will appear in a submenu; just click on one and it's done.
- Move to Map - This will move the screen to the list of another opened map, removing it from the current map. Choose one from the submenu and the screen will be spirited away.
With a screen highlighted, hit the delete key to remove it from the list. (This is undo-able.)
Main Screen - Map
Here's where the rubber hits the road; the fat hits the pan; the stormtrooper hits the bulkhead. Empty maps will show up as a black screen with fine blue gridlines delineating each screen (if your map has a lot of screens and/or the window size is small, they may be hard to see). You can resize the ZG window as needed to get a comfortable working size. The map will shrink and grow, but always display at the correct aspect ratio, with gray borders if needed.
Above the map area is its title, which you can double-click to edit. Hit Enter to accept the new name or Escape to cancel. To its right is a display of the map's output screen dimensions, for reference.
Hold down the Z key to show a floating window over the map, showing the area under the cursor at its full output size. The window will be the size of one full-output-size screen. Move the mouse while holding down the Z key and the zoom area will follow along. Release and the window vanishes.
To start building your map, left click a screen in the Captured Screens list to select one to work with, then pick the screen on the map you wish to place it.
- Middle-click - Place: the selected screen will be placed in the grid location you clicked. If you don't have a middle mouse button, hold down Alt and Left-click to place a screen. After it's been placed, you can still middle-click other screens to place it at a new location; it will disappear from the last screen it was placed. The text beside the Capture in the list will update to display its location in grid coordinates, that is (x, y). The current location of the mouse pointer, in grid coordinates, will appear in the left of the ZG window status bar.
- Left-click - Select/Move: clicking on a screen (without Shift or Ctrl held) will select the screen in the Captured Screens list. If you click and hold on a screen, you can drag it (it will show as a thick outline) to another grid location and release to move it there. If another screen was already there, it will be removed. If there are selected screens and you click outside of the selection, the screens will be deselected.
- Moving: If you click inside a selection (as shown by the 'move all' mouse cursor) and drag, you can move every selected screen (keeping their relative position to one another) around the map. Release to place them in a new position. The selection will stay after moving, so they can be repositioned as many times as you need. CAUTION: If part of your selection is moved outside the map's area, it will try to wrap those screens to the other side of the map, but they will be removed from the selection so they can't be repositioned from there. Sometimes at this point (or if you keep re-moving the now-current selection) strange things might happen, like screens hopping around to unwanted grid locations. You should be able to "undo" out of any trouble. Use the Map Move buttons if you need to "wrap" screens around.
- Holding Shift down will switch into Area Select mode. The mouse cursor will be an arrow with a thin rectangle below it. With Shift held, click and drag to draw a rectangle, displayed as a fine dotted line. When you release the mouse, any screen that has any part within the borders of the rectangle will be selected. The selection area will be drawn with thick borders. If there was already a selection, it will be overridden with this selection. Only grid locations that have a screen placed in them will be selected. So, if you drag and select a square area, but there are only 3 screens in an "L" configuration inside, the selection area will be on only those screens -- thus in the shape of an "L".
- Holding Ctrl down will switch into Add/Remove from selection mode. If you are outside of a selection area, clicking will Add the screen under the cursor to the selection. If you are inside an area, clicking will remove the screen the cursor is over from the selection. The mouse cursor will change to an arrow with a thick rectangle with either a plus + or minus - above it to let you know what will happen when you click. You can select any placed screen at any grid on the map; they do not have to be contiguous. Use in conjunction with Shift to quickly select incongruous screens. For example, if there's just one screen you don't want out of a large area, select all with Area Select (Shift) first, then hold Ctrl and deselect the unwanted. Be sure to use Area Select first, as it replaces already-selected screens.
- Right-click - Removes the screen the cursor is over from the map, and sets its state in the Captured list to 'not set'.
Settings dialog
There are three pages in the settings dialog: Image Capture, Saved Maps, and Export.
Image Capture:
- Capture Hot Key: This is how you capture all those screenshots. This is a system-wide Hot Key that will trigger ZeldaGrabber to take a screenshot no matter what window you're currently working in. Note, however, that if another program uses the chosen key or key combination, it will still be work if you're working in that program (in other words, ZG doesn't completely 'steal' the key). So, be sure that the chosen hot key is not used by any program you'll be using ZG with. It can be a single key or modified with Ctrl, Shift, and Alt -- even all of them together (it can't be just them, however). To set one, hit Enter while the hot key text box has focus, or double-click on it. It will turn yellow to show it's watching. If you don't select a key within 7 seconds, it will stop watching. If you wish to use modifiers, be sure to have them pressed first before you press the final 'main' key. For example, if you want Ctrl+Shift+S, hold the Ctrl and Shift keys down before you press the S key. Note: there are some keys which cannot be used, like Windows Key combinations; F12 is also supposedly reserved, but I've seen it be accepted. The hot key will be set when you click OK in the settings dialog; it will let you know if there were errors setting it.
- Window Title/Class: These values define the target window that you capture screenshots from. Internally, windows recognize each other by a title (shown at the top of the window) and a class. It's like they're stuck reliving the glory days of high school ("Valedictorian, class of '02!" "Shut up, Chris; the fries are burning."). You can enter new info in these text boxes. Anyway, you don't need to bother with these details unless you want to use ZG with other applications -- which you can certainly do. The only quirk is the Captured list will always display things at what [I presume] is the natural ratio of ZC's screen area: 32:21.
- Defaults (Title/Class): Click this to load the title and class text boxes with the info for most ZeldaClassic versions [...that I've seen; let me know if something changes].
- Select Window: To pick another window to capture from, you can click and drag the targeting reticle onto a window, and ZG will learn its title and class. Currently, it expects an unchanging window title (that limitation can be removed in the future).
- Use newer capture method: There are a few ways to capture the window. Checking this box will use a technique which usually works better. With this checked, you probably won't have to worry about having another window covering the target window. Either method, the target window must not be minimized to capture a screenshot. There may be bugs in this new method -- I've had to work around a ridiculous one in XP (it's not present in Vista or later). So, I've left it as optional, and if you see your captures are offset from where they're supposed to be, you can turn it off.
- Capture Area: This is the rectangle within the target window that will be captured for each screen. Clicking the Defaults button near these fields will load the default values for a 640x480 instance of ZC. It is in pixels, relative to the upper-left corner of what's known as the window's "client area". Most windows' client area is the space inside the borders; that is, excluding the title bar and menu bar (if present). But you don't really have to just guess at these values because we have...
- Select Capture Area... - If the target window is found, loads a dialog to simply, visually pick out the capture area. See Select Capture Area dialog for more info.
Saved Maps: there's only one lonely control in here. Stop by and say hi sometime. As the save options now appear in the Save File As... dialog, this page now functions as the "default" save settings: selecting which options will be already checked when the Save As dialog appears.
- Minimize save file size: Check to minimize the save file size, if possible. Here's how it works: say you're capturing an area from a 640x480 ZC. The capture dimensions are 512x336. However, if you created the map's output size as 256x168 (50%), then logically that's the largest size capture you need (especially since the native resolution is 256x168 ...I presume). So, when the file is saved, the captures will be resized to the output size. Unchecked, the full-sized images, as captured, will be saved. The size change is roughly proportional to the square of the scale difference. So, 50% output (1/2) squared = 1/4 the regular file size. (A 12MB file becomes 3MB.)
- Compress save files: using the included zlib.dll, the data in the saves will be losslessly compressed. This can greatly shrink the save files for simple tilesets (1.2% of the nominal size!), less so for more complicated ones.
- Apply touch-ups on save: This will permanently apply the Touch-up patches onto the Target screens. Also, with this option on, if there are screens that are only Sources, and are not placed on the map, they will not be saved in the file.
Export:
- Background color: When you export the map's image, you have the option of selecting either a colored background (behind any "blank"/unfilled screens) or a background image. Click on the color rectangle to show a standard color picker dialog and select a color. (In future versions, I could possibly export with transparency for supported image types.)
- Background picture: Draw a selected image "under" the map (again, showing in blank screens). The image will be stretched or shrunk to fit the map's dimensions. If Keep aspect ratio is checked, it will be drawn with the proper aspect ratio, and any spaces not covered due to aspect ratio difference will show as the Background color. If unchecked, the image will fill the entire map area (so there will be no uncovered areas).
Select Capture Area dialog
The button on the Settings:Image Capture page will open this dialog (if the target window is present). Note that it works on the window title/class that's currently showing in the Settings dialog; this also goes for the current state of the Newer capture method checkbox.
Upon loading, the dialog will grab a screenshot of the entire target window to display at the bottom, sizing itself to fit. A thick border will edge the current capture area. At the top is basically a duplicate of the Capture area from the Image Capture page. Click the Save button when you've adjusted the area properly, or Cancel to dismiss the dialog without updating the Settings dialog. There are several ways to set the area from this dialog:
- Type the values in the text boxes directly
- Keyboard shortcuts: the arrow keys can be used to scoot the borders around precisely. Up/Down moves the top border, Ctrl+Up/Down moves the bottom. Left/Right moves the left border, and, likewise, adding Ctrl to them moves the right border. Note that these are global to the entire dialog, so moving the cursor in the text boxes is a bit tricky. You can just select the entire text with the mouse and type over it; the selection will only update once you move focus to another control.
- Grab the borders in the display and drag to size the area, just like you would resize a window. Or, put the mouse cursor within the selection area and click and drag the entire selection around
- The window display, like the main map, supports selecting an area. Hold Shift and left click, then drag to select the new rectangle.
This dialog also has undo functionality. Click the Undo or Redo buttons at top, or press Ctrl+Z or Shift+Ctrl+Z. Note that if you're using the arrow keys to size, a new undo state is only saved when you release the keys you're pressing. So, you can hold down a key to move it a long distance, and it will only save the next position as you release (bypassing all the intermediate values).
There are three additional shortcut keys you can use in this dialog:
- Z key: Zoom in on the screen capture. While you hold it down, a small floating window will appear showing the area under your mouse cursor at twice the normal size. Move the cursor to wherever you need a closer look. Release the key and the zoom view disappears.
- V key: View just the selection area. The rest of the capture will turn black, the borders will vanish, and only the selected area will be displayed. This is great for getting a precise look at the area, without the borders covering the edges. You can combine the Z and V key to get a clean, zoomed view (press the V key first).
- F5 key: Refresh the capture display. Grabs a new screenshot of the target program.
----------
Well, I think that's about it for instructions. Now for some other important things to remember:
- Consider this a work in progress. It's quite stable, but you may experience things like issues moving multiple selected screens, flickering, or just an occasional "actin' stupid".
- As mentioned, multiple selected screens wrapping around is buggy.
- The selection border drawn in the Select Capture Area dialog can leave 'ghosts' of itself in some situations. Hitting F5 to refresh the view should fix this.
- The save files get large -- fast. As in 44MB for an 8x8 map with every screen filled when you capture and save at 512x336. The Compress Save File option is highly recommended. If you're running this on a really low-memory machine, then keep in mind the same map will take even more than that in RAM. But that's completely filled maps, again.
If you're not going to be using some .zcmaps for a while, go ahead and Rar them. The low bit depth maps (like the original quests) compress startlingly well. Original quest Level 3, on a map by itself, 19 screens, 512x336 size captures: 13,074,859 bytes as a file; compresses to 64,770 bytes.And don't forget to enable the Minimize save file size option when you can. - Remember that most exported images (jpg, png, and tiff) contain the information required to recreate a map. This is the good way for two quest makers to collaborate if they need to pass ideas back and forth over the internet. Of course, compressed .zcmaps now work about as well. However, if you edit an exported image with a bossy program that overwrites image files' metadata, the ZG information will likely get deleted. This is also likely for online image hosts.
- If you are unable to use the newer capture method: it's annoying, but due to the way Windows' graphics system works (and not very forthcoming documentation), you will have to have the ZC (target) window be unobstructed by others. That is, have no other windows covering the captured portion of it, otherwise, when you get a screen capture, they may appear in the screenshot.
- Similarly, the ZC window definitely can't be minimized to take a screenshot. ZG will try to restore a minimized target window when taking a capture.
So, there we have it. Let me know about issues you have installing or running it, and let me know what features it's missing. I already thought of some, like being able to find windows with changing titles, pasting screens into the captured list, and maybe a method of inserting text onto the map.
Whew, I think writing this post took more time than writing the code. Take care.
Edited by AviSoft, 05 December 2014 - 02:25 AM.
I'll get a website for it one of these days.
