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