1 /** @file 2 FormDiplay protocol to show Form 3 4 Copyright (c) 2013 - 2014, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials are licensed and made available under 6 the terms and conditions of the BSD License that accompanies this distribution. 7 The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php. 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef __FORM_DISPLAY_H__ 16 #define __FORM_DISPLAY_H__ 17 18 19 #include <Library/UefiBootServicesTableLib.h> 20 #include <Library/DebugLib.h> 21 #include <Library/BaseMemoryLib.h> 22 #include <Library/BaseLib.h> 23 #include <Library/HiiLib.h> 24 #include <Library/MemoryAllocationLib.h> 25 #include <Library/PrintLib.h> 26 #include <Library/CustomizedDisplayLib.h> 27 28 #include <Protocol/FormBrowserEx2.h> 29 #include <Protocol/SimpleTextIn.h> 30 #include <Protocol/DisplayProtocol.h> 31 32 #include <Guid/MdeModuleHii.h> 33 34 // 35 // This is the generated header file which includes whatever needs to be exported (strings + IFR) 36 // 37 extern UINT8 DisplayEngineStrings[]; 38 extern EFI_SCREEN_DESCRIPTOR gStatementDimensions; 39 extern USER_INPUT *gUserInput; 40 extern FORM_DISPLAY_ENGINE_FORM *gFormData; 41 extern EFI_HII_HANDLE gHiiHandle; 42 extern UINT16 gDirection; 43 extern LIST_ENTRY gMenuOption; 44 45 // 46 // Browser Global Strings 47 // 48 extern CHAR16 *gSaveFailed; 49 extern CHAR16 *gPromptForData; 50 extern CHAR16 *gPromptForPassword; 51 extern CHAR16 *gPromptForNewPassword; 52 extern CHAR16 *gConfirmPassword; 53 extern CHAR16 *gConfirmError; 54 extern CHAR16 *gPassowordInvalid; 55 extern CHAR16 *gPressEnter; 56 extern CHAR16 *gEmptyString; 57 extern CHAR16 *gMiniString; 58 extern CHAR16 *gOptionMismatch; 59 extern CHAR16 *gFormSuppress; 60 extern CHAR16 *gProtocolNotFound; 61 62 extern CHAR16 gPromptBlockWidth; 63 extern CHAR16 gOptionBlockWidth; 64 extern CHAR16 gHelpBlockWidth; 65 extern CHAR16 *mUnknownString; 66 extern BOOLEAN gMisMatch; 67 68 // 69 // Screen definitions 70 // 71 72 #define LEFT_SKIPPED_COLUMNS 3 73 #define SCROLL_ARROW_HEIGHT 1 74 #define POPUP_PAD_SPACE_COUNT 5 75 #define POPUP_FRAME_WIDTH 2 76 77 #define UPPER_LOWER_CASE_OFFSET 0x20 78 79 // 80 // Display definitions 81 // 82 #define LEFT_ONEOF_DELIMITER L'<' 83 #define RIGHT_ONEOF_DELIMITER L'>' 84 85 #define LEFT_NUMERIC_DELIMITER L'[' 86 #define RIGHT_NUMERIC_DELIMITER L']' 87 88 #define LEFT_CHECKBOX_DELIMITER L'[' 89 #define RIGHT_CHECKBOX_DELIMITER L']' 90 91 #define CHECK_ON L'X' 92 #define CHECK_OFF L' ' 93 94 #define TIME_SEPARATOR L':' 95 #define DATE_SEPARATOR L'/' 96 97 #define SUBTITLE_INDENT 2 98 99 // 100 // This is the Input Error Message 101 // 102 #define INPUT_ERROR 1 103 104 // 105 // This is the NV RAM update required Message 106 // 107 #define NV_UPDATE_REQUIRED 2 108 // 109 // Time definitions 110 // 111 #define ONE_SECOND 10000000 112 113 // 114 // It take 23 characters including the NULL to print a 64 bits number with "[" and "]". 115 // pow(2, 64) = [18446744073709551616] 116 // with extra '-' flat, set the width to 24. 117 // 118 #define MAX_NUMERIC_INPUT_WIDTH 24 119 120 #define EFI_HII_EXPRESSION_INCONSISTENT_IF 0 121 #define EFI_HII_EXPRESSION_NO_SUBMIT_IF 1 122 #define EFI_HII_EXPRESSION_GRAY_OUT_IF 2 123 #define EFI_HII_EXPRESSION_SUPPRESS_IF 3 124 #define EFI_HII_EXPRESSION_DISABLE_IF 4 125 126 // 127 // Character definitions 128 // 129 #define CHAR_SPACE 0x0020 130 131 #define FORM_DISPLAY_DRIVER_SIGNATURE SIGNATURE_32 ('F', 'D', 'D', 'V') 132 typedef struct { 133 UINT32 Signature; 134 135 EFI_HANDLE Handle; 136 137 // 138 // Produced protocol 139 // 140 EDKII_FORM_DISPLAY_ENGINE_PROTOCOL FromDisplayProt; 141 } FORM_DISPLAY_DRIVER_PRIVATE_DATA; 142 143 144 typedef enum { 145 UiNoOperation, 146 UiSelect, 147 UiUp, 148 UiDown, 149 UiLeft, 150 UiRight, 151 UiReset, 152 UiPrevious, 153 UiPageUp, 154 UiPageDown, 155 UiHotKey, 156 UiMaxOperation 157 } UI_SCREEN_OPERATION; 158 159 typedef enum { 160 CfInitialization, 161 CfCheckSelection, 162 CfRepaint, 163 CfRefreshHighLight, 164 CfUpdateHelpString, 165 CfPrepareToReadKey, 166 CfReadKey, 167 CfScreenOperation, 168 CfUiSelect, 169 CfUiReset, 170 CfUiLeft, 171 CfUiRight, 172 CfUiUp, 173 CfUiPageUp, 174 CfUiPageDown, 175 CfUiDown, 176 CfUiNoOperation, 177 CfExit, 178 CfUiHotKey, 179 CfMaxControlFlag 180 } UI_CONTROL_FLAG; 181 182 typedef enum { 183 UIEventNone, 184 UIEventKey, 185 UIEventTimeOut, 186 UIEventDriver 187 } UI_EVENT_TYPE; 188 189 typedef struct { 190 UINT16 ScanCode; 191 UI_SCREEN_OPERATION ScreenOperation; 192 } SCAN_CODE_TO_SCREEN_OPERATION; 193 194 typedef struct { 195 UI_SCREEN_OPERATION ScreenOperation; 196 UI_CONTROL_FLAG ControlFlag; 197 } SCREEN_OPERATION_T0_CONTROL_FLAG; 198 199 typedef struct { 200 EFI_HII_HANDLE HiiHandle; 201 UINT16 FormId; 202 203 // 204 // Info for the highlight question. 205 // HLT means highlight 206 // 207 // If one statement has questionid, save questionid info to find the question. 208 // If one statement not has questionid info, save the opcode info to find the 209 // statement. If more than one statement has same opcode in one form(just like 210 // empty subtitle info may has more than one info one form), also use Index 211 // info to find the statement. 212 // 213 EFI_QUESTION_ID HLTQuestionId; 214 EFI_IFR_OP_HEADER *HLTOpCode; 215 UINTN HLTIndex; 216 UINTN HLTSequence; 217 218 // 219 // Info for the top of screen question. 220 // TOS means Top Of Screen 221 // 222 EFI_QUESTION_ID TOSQuestionId; 223 EFI_IFR_OP_HEADER *TOSOpCode; 224 UINTN TOSIndex; 225 226 UINT16 SkipValue; 227 } DISPLAY_HIGHLIGHT_MENU_INFO; 228 229 typedef struct { 230 EFI_EVENT SyncEvent; 231 UINT8 *TimeOut; 232 CHAR16 *ErrorInfo; 233 } WARNING_IF_CONTEXT; 234 235 #define UI_MENU_OPTION_SIGNATURE SIGNATURE_32 ('u', 'i', 'm', 'm') 236 237 typedef struct { 238 UINTN Signature; 239 LIST_ENTRY Link; 240 241 EFI_HII_HANDLE Handle; 242 FORM_DISPLAY_ENGINE_STATEMENT *ThisTag; 243 UINT16 EntryNumber; 244 245 UINTN Row; 246 UINTN Col; 247 UINTN OptCol; 248 CHAR16 *Description; 249 UINTN Skip; // Number of lines 250 251 // 252 // Display item sequence for date/time 253 // Date: Month/Day/Year 254 // Sequence: 0 1 2 255 // 256 // Time: Hour : Minute : Second 257 // Sequence: 0 1 2 258 // 259 // 260 UINTN Sequence; 261 262 BOOLEAN GrayOut; 263 BOOLEAN ReadOnly; 264 265 // 266 // Whether user could change value of this item 267 // 268 BOOLEAN IsQuestion; 269 BOOLEAN NestInStatement; 270 } UI_MENU_OPTION; 271 272 #define MENU_OPTION_FROM_LINK(a) CR (a, UI_MENU_OPTION, Link, UI_MENU_OPTION_SIGNATURE) 273 274 /** 275 Print Question Value according to it's storage width and display attributes. 276 277 @param Question The Question to be printed. 278 @param FormattedNumber Buffer for output string. 279 @param BufferSize The FormattedNumber buffer size in bytes. 280 281 @retval EFI_SUCCESS Print success. 282 @retval EFI_BUFFER_TOO_SMALL Buffer size is not enough for formatted number. 283 284 **/ 285 EFI_STATUS 286 PrintFormattedNumber ( 287 IN FORM_DISPLAY_ENGINE_STATEMENT *Question, 288 IN OUT CHAR16 *FormattedNumber, 289 IN UINTN BufferSize 290 ); 291 292 /** 293 Set value of a data element in an Array by its Index. 294 295 @param Array The data array. 296 @param Type Type of the data in this array. 297 @param Index Zero based index for data in this array. 298 @param Value The value to be set. 299 300 **/ 301 VOID 302 SetArrayData ( 303 IN VOID *Array, 304 IN UINT8 Type, 305 IN UINTN Index, 306 IN UINT64 Value 307 ); 308 309 /** 310 Return data element in an Array by its Index. 311 312 @param Array The data array. 313 @param Type Type of the data in this array. 314 @param Index Zero based index for data in this array. 315 316 @retval Value The data to be returned 317 318 **/ 319 UINT64 320 GetArrayData ( 321 IN VOID *Array, 322 IN UINT8 Type, 323 IN UINTN Index 324 ); 325 326 /** 327 Search an Option of a Question by its value. 328 329 @param Question The Question 330 @param OptionValue Value for Option to be searched. 331 332 @retval Pointer Pointer to the found Option. 333 @retval NULL Option not found. 334 335 **/ 336 DISPLAY_QUESTION_OPTION * 337 ValueToOption ( 338 IN FORM_DISPLAY_ENGINE_STATEMENT *Question, 339 IN EFI_HII_VALUE *OptionValue 340 ); 341 342 /** 343 Compare two Hii value. 344 345 @param Value1 Expression value to compare on left-hand. 346 @param Value2 Expression value to compare on right-hand. 347 @param Result Return value after compare. 348 retval 0 Two operators equal. 349 return Positive value if Value1 is greater than Value2. 350 retval Negative value if Value1 is less than Value2. 351 @param HiiHandle Only required for string compare. 352 353 @retval other Could not perform compare on two values. 354 @retval EFI_SUCCESS Compare the value success. 355 356 **/ 357 EFI_STATUS 358 CompareHiiValue ( 359 IN EFI_HII_VALUE *Value1, 360 IN EFI_HII_VALUE *Value2, 361 OUT INTN *Result, 362 IN EFI_HII_HANDLE HiiHandle OPTIONAL 363 ); 364 365 /** 366 Draw a pop up windows based on the dimension, number of lines and 367 strings specified. 368 369 @param RequestedWidth The width of the pop-up. 370 @param NumberOfLines The number of lines. 371 @param ... A series of text strings that displayed in the pop-up. 372 373 **/ 374 VOID 375 EFIAPI 376 CreateMultiStringPopUp ( 377 IN UINTN RequestedWidth, 378 IN UINTN NumberOfLines, 379 ... 380 ); 381 382 /** 383 Will copy LineWidth amount of a string in the OutputString buffer and return the 384 number of CHAR16 characters that were copied into the OutputString buffer. 385 The output string format is: 386 Glyph Info + String info + '\0'. 387 388 In the code, it deals \r,\n,\r\n same as \n\r, also it not process the \r or \g. 389 390 @param InputString String description for this option. 391 @param LineWidth Width of the desired string to extract in CHAR16 392 characters 393 @param GlyphWidth The glyph width of the begin of the char in the string. 394 @param Index Where in InputString to start the copy process 395 @param OutputString Buffer to copy the string into 396 397 @return Returns the number of CHAR16 characters that were copied into the OutputString 398 buffer, include extra glyph info and '\0' info. 399 400 **/ 401 UINT16 402 GetLineByWidth ( 403 IN CHAR16 *InputString, 404 IN UINT16 LineWidth, 405 IN OUT UINT16 *GlyphWidth, 406 IN OUT UINTN *Index, 407 OUT CHAR16 **OutputString 408 ); 409 410 411 /** 412 Get the string based on the StringId and HII Package List Handle. 413 414 @param Token The String's ID. 415 @param HiiHandle The Hii handle for this string package. 416 417 @return The output string. 418 419 **/ 420 CHAR16 * 421 GetToken ( 422 IN EFI_STRING_ID Token, 423 IN EFI_HII_HANDLE HiiHandle 424 ); 425 426 /** 427 Count the storage space of a Unicode string. 428 429 This function handles the Unicode string with NARROW_CHAR 430 and WIDE_CHAR control characters. NARROW_HCAR and WIDE_CHAR 431 does not count in the resultant output. If a WIDE_CHAR is 432 hit, then 2 Unicode character will consume an output storage 433 space with size of CHAR16 till a NARROW_CHAR is hit. 434 435 If String is NULL, then ASSERT (). 436 437 @param String The input string to be counted. 438 439 @return Storage space for the input string. 440 441 **/ 442 UINTN 443 GetStringWidth ( 444 IN CHAR16 *String 445 ); 446 447 /** 448 This routine reads a numeric value from the user input. 449 450 @param MenuOption Pointer to the current input menu. 451 452 @retval EFI_SUCCESS If numerical input is read successfully 453 @retval EFI_DEVICE_ERROR If operation fails 454 455 **/ 456 EFI_STATUS 457 GetNumericInput ( 458 IN UI_MENU_OPTION *MenuOption 459 ); 460 461 /** 462 Get string or password input from user. 463 464 @param MenuOption Pointer to the current input menu. 465 @param Prompt The prompt string shown on popup window. 466 @param StringPtr Old user input and destination for use input string. 467 468 @retval EFI_SUCCESS If string input is read successfully 469 @retval EFI_DEVICE_ERROR If operation fails 470 471 **/ 472 EFI_STATUS 473 ReadString ( 474 IN UI_MENU_OPTION *MenuOption, 475 IN CHAR16 *Prompt, 476 IN OUT CHAR16 *StringPtr 477 ); 478 479 /** 480 Draw a pop up windows based on the dimension, number of lines and 481 strings specified. 482 483 @param RequestedWidth The width of the pop-up. 484 @param NumberOfLines The number of lines. 485 @param Marker The variable argument list for the list of string to be printed. 486 487 **/ 488 VOID 489 CreateSharedPopUp ( 490 IN UINTN RequestedWidth, 491 IN UINTN NumberOfLines, 492 IN VA_LIST Marker 493 ); 494 495 /** 496 Wait for a key to be pressed by user. 497 498 @param Key The key which is pressed by user. 499 500 @retval EFI_SUCCESS The function always completed successfully. 501 502 **/ 503 EFI_STATUS 504 WaitForKeyStroke ( 505 OUT EFI_INPUT_KEY *Key 506 ); 507 508 /** 509 Get selection for OneOf and OrderedList (Left/Right will be ignored). 510 511 @param MenuOption Pointer to the current input menu. 512 513 @retval EFI_SUCCESS If Option input is processed successfully 514 @retval EFI_DEVICE_ERROR If operation fails 515 516 **/ 517 EFI_STATUS 518 GetSelectionInputPopUp ( 519 IN UI_MENU_OPTION *MenuOption 520 ); 521 522 /** 523 Process the help string: Split StringPtr to several lines of strings stored in 524 FormattedString and the glyph width of each line cannot exceed gHelpBlockWidth. 525 526 @param StringPtr The entire help string. 527 @param FormattedString The oupput formatted string. 528 @param EachLineWidth The max string length of each line in the formatted string. 529 @param RowCount TRUE: if Question is selected. 530 531 **/ 532 UINTN 533 ProcessHelpString ( 534 IN CHAR16 *StringPtr, 535 OUT CHAR16 **FormattedString, 536 OUT UINT16 *EachLineWidth, 537 IN UINTN RowCount 538 ); 539 540 /** 541 Process a Question's Option (whether selected or un-selected). 542 543 @param MenuOption The MenuOption for this Question. 544 @param Selected TRUE: if Question is selected. 545 @param OptionString Pointer of the Option String to be displayed. 546 @param SkipErrorValue Whether need to return when value without option for it. 547 548 @retval EFI_SUCCESS Question Option process success. 549 @retval Other Question Option process fail. 550 551 **/ 552 EFI_STATUS 553 ProcessOptions ( 554 IN UI_MENU_OPTION *MenuOption, 555 IN BOOLEAN Selected, 556 OUT CHAR16 **OptionString, 557 IN BOOLEAN SkipErrorValue 558 ); 559 560 /** 561 Set Buffer to Value for Size bytes. 562 563 @param Buffer Memory to set. 564 @param Size Number of bytes to set 565 @param Value Value of the set operation. 566 567 **/ 568 VOID 569 SetUnicodeMem ( 570 IN VOID *Buffer, 571 IN UINTN Size, 572 IN CHAR16 Value 573 ); 574 575 /** 576 Display one form, and return user input. 577 578 @param FormData Form Data to be shown. 579 @param UserInputData User input data. 580 581 @retval EFI_SUCCESS Form Data is shown, and user input is got. 582 **/ 583 EFI_STATUS 584 EFIAPI 585 FormDisplay ( 586 IN FORM_DISPLAY_ENGINE_FORM *FormData, 587 OUT USER_INPUT *UserInputData 588 ); 589 590 /** 591 Clear Screen to the initial state. 592 **/ 593 VOID 594 EFIAPI 595 DriverClearDisplayPage ( 596 VOID 597 ); 598 599 /** 600 Exit Display and Clear Screen to the original state. 601 602 **/ 603 VOID 604 EFIAPI 605 ExitDisplay ( 606 VOID 607 ); 608 609 /** 610 Process nothing. 611 612 @param Event The Event need to be process 613 @param Context The context of the event. 614 615 **/ 616 VOID 617 EFIAPI 618 EmptyEventProcess ( 619 IN EFI_EVENT Event, 620 IN VOID *Context 621 ); 622 623 /** 624 Process for the refresh interval statement. 625 626 @param Event The Event need to be process 627 @param Context The context of the event. 628 629 **/ 630 VOID 631 EFIAPI 632 RefreshTimeOutProcess ( 633 IN EFI_EVENT Event, 634 IN VOID *Context 635 ); 636 637 /** 638 Record the highlight menu and top of screen menu info. 639 640 @param Highlight The menu opton which is highlight. 641 @param TopOfScreen The menu opton which is at the top of the form. 642 @param SkipValue The skip line info for the top of screen menu. 643 644 **/ 645 VOID 646 UpdateHighlightMenuInfo ( 647 IN LIST_ENTRY *Highlight, 648 IN LIST_ENTRY *TopOfScreen, 649 IN UINTN SkipValue 650 ); 651 652 #endif 653